{ "openapi": "3.1.0", "info": { "title": "Bodhi App APIs", "description": "API documentation for Bodhi App.\n\n## Authentication Methods\n\nBodhi App supports three sophisticated authentication methods:\n\n### 1. API Token Authentication (Recommended for API access)\n- **Method**: Bearer token in Authorization header\n- **Format**: `Authorization: Bearer bodhiapp_`\n- **Obtain**: Create via web interface at Menu > Settings > API Tokens\n- **Scopes**: Token-based scopes with hierarchical permissions\n - `scope_token_user`: Basic API access (read operations, OpenAI/Ollama APIs)\n - `scope_token_power_user`: Advanced operations (model creation, downloads)\n - `scope_token_manager`: User management operations\n - `scope_token_admin`: Full administrative access\n- **Usage**: Best for programmatic access, CI/CD, and external integrations\n\n### 2. Session Authentication (Browser-based)\n- **Method**: HTTP cookies (automatic for browsers)\n- **Login**: Initiate via `POST /bodhi/v1/auth/initiate`\n- **Callback**: Complete via `POST /bodhi/v1/auth/callback`\n- **Roles**: Resource-based roles with hierarchical permissions\n - `resource_user`: Basic authenticated access\n - `resource_power_user`: Advanced operations\n - `resource_manager`: User management (session-only)\n - `resource_admin`: Full administration (session-only)\n- **Usage**: Best for web browsers and interactive applications\n- **Session-Only Operations**: Some sensitive operations (token management, settings, user management) require session authentication only for security\n\n### 3. OAuth 2.1 Token Exchange (External integrations)\n- **Method**: Bearer token with exchanged OAuth credentials\n- **Format**: `Authorization: Bearer `\n- **Scopes**: User-based scopes via OAuth 2.1 token exchange\n - `scope_user_user`: Basic user access via OAuth exchange\n - `scope_user_power_user`: Advanced user operations via OAuth exchange \n - `scope_user_manager`: Manager operations via OAuth exchange\n - `scope_user_admin`: Admin operations via OAuth exchange\n- **Usage**: For external OAuth 2.1 providers integrating with Bodhi\n\n## Authorization Hierarchy\n\n**Permission Hierarchy** (higher levels include all lower permissions):\n```\nAdmin > Manager > PowerUser > User\n```\n\n**Scope/Role Mapping**:\n| Permission Level | API Token Scope | OAuth User Scope | Session Role |\n|------------------|----------------|------------------|-------------|\n| User | `scope_token_user` | `scope_user_user` | `resource_user` |\n| PowerUser | `scope_token_power_user` | `scope_user_power_user` | `resource_power_user` |\n| Manager | `scope_token_manager` | `scope_user_manager` | `resource_manager` |\n| Admin | `scope_token_admin` | `scope_user_admin` | `resource_admin` |\n\n## Endpoint Access Patterns\n\n- **Public Endpoints**: No authentication required (ping, health, app_info, setup)\n- **Optional Auth Endpoints**: Work with or without authentication, providing different data (user_info)\n- **Multi-Auth Endpoints**: Accept any of the three authentication methods (most API endpoints)\n- **Session-Only Endpoints**: Require browser session authentication only:\n - Token management (`/bodhi/v1/tokens/*`) - PowerUser+ session required\n - Settings management (`/bodhi/v1/settings/*`) - Admin session required \n - User management (`/bodhi/v1/users/*`) - Manager+ session required\n\n## Security Examples\n\n### API Token Usage:\n```bash\ncurl -H \"Authorization: Bearer bodhiapp_1234567890abcdef\" \\\n https://api.example.com/v1/models\n```\n\n### Session Authentication:\n```bash\n# Login first\ncurl -X POST https://api.example.com/bodhi/v1/auth/initiate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"github\"}'\n\n# Then use session cookie automatically\ncurl https://api.example.com/v1/models \\\n --cookie-jar cookies.txt --cookie cookies.txt\n```\n\n### OAuth 2.1 Token Exchange:\n```bash\ncurl -H \"Authorization: Bearer \" \\\n https://api.example.com/v1/models\n```\n\n## Security Best Practices\n\n1. **Use HTTPS**: Always use HTTPS in production\n2. **Scope Principle**: Request minimal required scopes/roles\n3. **Token Rotation**: Regularly rotate API tokens\n4. **Session Security**: Session-only operations prevent token-based access to sensitive functions\n5. **Hierarchical Permissions**: Higher roles automatically include lower role permissions\n", "contact": { "name": "Bodhi API Support", "url": "https://github.com/BodhiSearch/BodhiApp/issues", "email": "support@getbodhi.app" }, "license": { "name": "" }, "version": "0.0.49-dev" }, "servers": [ { "url": "http://localhost:1135", "description": "Local running instance" } ], "paths": { "/api/chat": { "post": { "tags": [ "ollama" ], "summary": "Chat with Model (Ollama Compatible)", "description": "Creates a chat completion using Ollama API format. Supports both streaming and non-streaming responses with Ollama-specific options and response format.", "operationId": "chatOllamaModel", "requestBody": { "description": "Chat request in Ollama format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "messages": [ { "content": "You are a helpful assistant.", "role": "system" }, { "content": "Hello!", "role": "user" } ], "model": "llama2:chat", "options": { "num_predict": 100, "temperature": 0.7 }, "stream": true } } }, "required": true }, "responses": { "200": { "description": "Chat response", "content": { "application/json": { "schema": {}, "example": { "created_at": "2024-01-20T12:00:00.000000000Z", "done": true, "done_reason": "stop", "eval_count": 10, "eval_duration": "-1", "load_duration": "-1", "message": { "content": "Hello! How can I help you today?", "images": null, "role": "assistant" }, "model": "llama2:chat", "prompt_eval_count": 20, "prompt_eval_duration": "-1", "total_duration": 0.0 } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaError" }, "example": { "error": "model not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/api/show": { "post": { "tags": [ "ollama" ], "summary": "Show Model Details (Ollama Compatible)", "description": "Retrieves detailed information about a specific model in Ollama API compatible format. Includes model parameters, template, license, and configuration details.", "operationId": "showOllamaModel", "requestBody": { "description": "Model name to get details for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowRequest" }, "example": { "name": "llama2:chat" } } }, "required": true }, "responses": { "200": { "description": "Model details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowResponse" }, "example": { "details": { "families": null, "family": "unknown", "format": "gguf", "parameter_size": "", "parent_model": null, "quantization_level": "" }, "license": "", "model_info": {}, "modelfile": "", "modified_at": "2024-01-20T12:00:00.000000000Z", "parameters": "n_keep: 24\nstop:\n- <|start_header_id|>\n- <|end_header_id|>\n- <|eot_id|>\n", "template": "llama2" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaError" }, "example": { "error": "model not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/api/tags": { "get": { "tags": [ "ollama" ], "summary": "List Available Models (Ollama Compatible)", "description": "Returns a list of all available models in Ollama API compatible format. Includes model metadata such as size, modification time, and format details.", "operationId": "listOllamaModels", "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" }, "example": { "models": [ { "details": { "families": null, "family": "unknown", "format": "gguf", "parameter_size": "", "parent_model": null, "quantization_level": "" }, "digest": "sha256:abc123", "model": "llama2:chat", "modified_at": "2024-01-20T12:00:00.000000000Z", "size": 0 } ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/bodhi/v1/access-requests": { "get": { "tags": [ "auth" ], "summary": "List All Access Requests", "description": "List all access requests regardless of status. Requires manager or admin role.", "operationId": "listAllAccessRequests", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All requests retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUserAccessResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/access-requests/pending": { "get": { "tags": [ "auth" ], "summary": "List Pending Access Requests", "description": "List all pending access requests. Requires manager or admin role.", "operationId": "listPendingAccessRequests", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending requests retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUserAccessResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/access-requests/{id}/approve": { "put": { "tags": [ "auth" ], "summary": "Approve Access Request", "description": "Approve access request with tool instance selections. Requires session auth.", "operationId": "approveAppsAccessRequest", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Approval details with tool selections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAccessRequest" } } }, "required": true }, "responses": { "200": { "description": "Request approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestActionResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "409": { "description": "Already processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [] } ] }, "post": { "tags": [ "auth" ], "summary": "Approve Access Request", "description": "Approve an access request and assign a role. Requires manager or admin role.", "operationId": "approveAccessRequest", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Role to assign to the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveUserAccessRequest" } } }, "required": true }, "responses": { "200": { "description": "Request approved successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/access-requests/{id}/deny": { "post": { "tags": [ "auth" ], "summary": "Deny Access Request", "description": "Deny access request. Requires session auth.", "operationId": "denyAccessRequest", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestActionResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "409": { "description": "Already processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [] } ] } }, "/bodhi/v1/access-requests/{id}/reject": { "post": { "tags": [ "auth" ], "summary": "Reject Access Request", "description": "Reject an access request. Requires manager or admin role.", "operationId": "rejectAccessRequest", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request rejected successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/access-requests/{id}/review": { "get": { "tags": [ "auth" ], "summary": "Get Access Request Review", "description": "Get full access request details for review page. Returns data regardless of status. Requires session auth.", "operationId": "getAccessRequestReview", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Review data retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestReviewResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "410": { "description": "Request expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [] } ] } }, "/bodhi/v1/apps/access-requests/{id}": { "get": { "tags": [ "auth" ], "summary": "Get Access Request Status", "description": "Poll access request status. Requires app_client_id query parameter for security.", "operationId": "getAccessRequestStatus", "parameters": [ { "name": "id", "in": "path", "description": "Access request ID", "required": true, "schema": { "type": "string" } }, { "name": "app_client_id", "in": "query", "description": "App client ID for verification", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestStatusResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found or app_client_id mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {} ] } }, "/bodhi/v1/apps/mcps": { "get": { "tags": [ "apps" ], "summary": "List MCP instances accessible to the authenticated external app", "operationId": "appsListMcps", "responses": { "200": { "description": "List of MCP instances accessible to the external app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMcpsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_oauth_token": [] } ] } }, "/bodhi/v1/apps/mcps/{id}": { "get": { "tags": [ "apps" ], "summary": "Get a specific MCP instance by ID via external app", "operationId": "appsGetMcp", "parameters": [ { "name": "id", "in": "path", "description": "MCP instance UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mcp" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "MCP not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_oauth_token": [] } ] } }, "/bodhi/v1/apps/mcps/{id}/mcp": { "post": { "tags": [ "mcps" ], "summary": "Transparent MCP proxy endpoint", "description": "Forwards MCP Streamable HTTP requests (POST/GET/DELETE) to upstream MCP server with auth injection", "operationId": "mcpProxy", "parameters": [ { "name": "id", "in": "path", "description": "MCP instance UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upstream response forwarded" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_oauth_token": [] } ] } }, "/bodhi/v1/apps/request-access": { "post": { "tags": [ "auth" ], "summary": "Create Access Request", "description": "Create an access request for an app to access user resources. Always creates a draft for user review. Unauthenticated endpoint.", "operationId": "createAccessRequest", "requestBody": { "description": "Access request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessRequest" } } }, "required": true }, "responses": { "201": { "description": "Access request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessRequestResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "App client not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {} ] } }, "/bodhi/v1/auth/callback": { "post": { "tags": [ "auth" ], "summary": "Complete OAuth Authentication", "description": "Completes the OAuth authentication flow by exchanging authorization code for tokens and establishing user session.", "operationId": "completeOAuthFlow", "requestBody": { "description": "OAuth callback parameters from authorization server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCallbackRequest" }, "example": { "code": "auth_code_123", "state": "random_state_456" } } }, "required": true }, "responses": { "200": { "description": "OAuth flow completed successfully, user authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" }, "example": { "location": "https://app.example.com/dashboard" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "422": { "description": "OAuth error, invalid request parameters, or state mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "oauth_state_mismatch", "message": "State parameter mismatch", "type": "invalid_request_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/auth/dashboard/callback": { "post": { "tags": [ "auth" ], "summary": "Complete Dashboard OAuth Authentication", "description": "Completes the dashboard OAuth authentication flow by exchanging authorization code for tokens.", "operationId": "completeDashboardOAuthFlow", "requestBody": { "description": "OAuth callback parameters from authorization server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCallbackRequest" } } }, "required": true }, "responses": { "200": { "description": "Dashboard OAuth flow completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/auth/dashboard/initiate": { "post": { "tags": [ "auth" ], "summary": "Initiate Dashboard OAuth Authentication", "description": "Initiates the dashboard OAuth authentication flow using the multi-tenant client. Only available in multi-tenant mode.", "operationId": "initiateDashboardOAuthFlow", "requestBody": { "content": { "application/json": { "schema": { "default": null } } }, "required": true }, "responses": { "200": { "description": "User already has a valid dashboard token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" } } } }, "201": { "description": "OAuth authorization URL provided for dashboard login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/auth/initiate": { "post": { "tags": [ "auth" ], "summary": "Initiate OAuth Authentication", "description": "Initiates OAuth authentication flow. Returns OAuth authorization URL for unauthenticated users or home page URL for already authenticated users.", "operationId": "initiateOAuthFlow", "requestBody": { "description": "OAuth initiate parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthInitiateRequest" } } }, "required": true }, "responses": { "200": { "description": "User already authenticated, home page URL provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" }, "example": { "location": "https://app.example.com/dashboard" } } } }, "201": { "description": "User not authenticated, OAuth authorization URL provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" }, "example": { "location": "https://auth.example.com/auth?client_id=bodhi&redirect_uri=..." } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/info": { "get": { "tags": [ "system" ], "summary": "Get Application Information", "description": "Retrieves current application version and status information including setup state", "operationId": "getAppInfo", "responses": { "200": { "description": "Application information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfo" }, "example": { "client_id": "my-client-id", "commit_sha": "abc1234", "deployment": "standalone", "status": "ready", "url": "https://example.com", "version": "0.1.0" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } } } }, "/bodhi/v1/logout": { "post": { "tags": [ "auth" ], "summary": "Logout User", "description": "Logs out the current user by destroying their session and returns redirect URL to login page", "operationId": "logoutUser", "responses": { "200": { "description": "User logged out successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectResponse" }, "example": { "location": "https://app.example.com/login" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } } } }, "/bodhi/v1/mcps": { "get": { "tags": [ "mcps" ], "summary": "List all MCP instances for the authenticated user", "operationId": "listMcps", "responses": { "200": { "description": "List of user's MCP instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMcpsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "mcps" ], "summary": "Create a new MCP instance", "operationId": "createMcp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRequest" } } }, "required": true }, "responses": { "201": { "description": "MCP created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mcp" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/auth-configs": { "get": { "tags": [ "mcps" ], "summary": "List all auth configs for an MCP server (headers + OAuth configs)", "operationId": "listMcpAuthConfigs", "parameters": [ { "name": "mcp_server_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of auth configs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthConfigsListResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "mcps" ], "summary": "Create a new auth config (header, OAuth pre-registered, or OAuth dynamic)", "operationId": "createMcpAuthConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthConfig" } } }, "required": true }, "responses": { "201": { "description": "Auth config created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthConfigResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/auth-configs/{id}": { "get": { "tags": [ "mcps" ], "summary": "Get an auth config by ID", "operationId": "getMcpAuthConfig", "parameters": [ { "name": "id", "in": "path", "description": "Auth config UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auth config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthConfigResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "mcps" ], "summary": "Delete an auth config by ID (cascades to tokens if OAuth)", "operationId": "deleteMcpAuthConfig", "parameters": [ { "name": "id", "in": "path", "description": "Auth config UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Auth config deleted" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/auth-configs/{id}/login": { "post": { "tags": [ "mcps" ], "summary": "Initiate OAuth login for a config", "operationId": "mcpOAuthLogin", "parameters": [ { "name": "id", "in": "path", "description": "Auth config UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Authorization URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthLoginResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Auth config not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/auth-configs/{id}/token": { "post": { "tags": [ "mcps" ], "summary": "Exchange authorization code for tokens", "operationId": "mcpOAuthTokenExchange", "parameters": [ { "name": "id", "in": "path", "description": "Auth config UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenExchangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Token stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Auth config not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/oauth-tokens/{token_id}": { "get": { "tags": [ "mcps" ], "summary": "Get an OAuth token by ID", "operationId": "getMcpOAuthToken", "parameters": [ { "name": "token_id", "in": "path", "description": "OAuth token UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "mcps" ], "summary": "Delete an OAuth token by ID", "operationId": "deleteMcpOAuthToken", "parameters": [ { "name": "token_id", "in": "path", "description": "OAuth token UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "OAuth token deleted" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/oauth/discover-as": { "post": { "tags": [ "mcps" ], "summary": "Discover OAuth metadata from an authorization server URL (RFC 8414)", "operationId": "mcpOAuthDiscoverAs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDiscoverAsRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth discovery metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDiscoverAsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/oauth/discover-mcp": { "post": { "tags": [ "mcps" ], "summary": "Discover OAuth metadata from an MCP server URL (RFC 9728 + RFC 8414)", "operationId": "mcpOAuthDiscoverMcp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDiscoverMcpRequest" } } }, "required": true }, "responses": { "200": { "description": "MCP OAuth discovery metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthDiscoverMcpResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/oauth/dynamic-register": { "post": { "tags": [ "mcps" ], "summary": "Standalone dynamic client registration (no server_id required)", "operationId": "mcpOAuthDynamicRegisterStandalone", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicRegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "Dynamic client registration result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicRegisterResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/servers": { "get": { "tags": [ "mcps" ], "summary": "List MCP servers, optionally filtered by enabled status", "operationId": "listMcpServers", "parameters": [ { "name": "enabled", "in": "query", "description": "Filter by enabled status", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of MCP servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMcpServersResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "mcps" ], "summary": "Create a new MCP server entry (admin/manager only)", "operationId": "createMcpServer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerRequest" } } }, "required": true }, "responses": { "201": { "description": "MCP server created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "409": { "description": "URL already exists" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/servers/{id}": { "get": { "tags": [ "mcps" ], "summary": "Get a specific MCP server by ID", "operationId": "getMcpServer", "parameters": [ { "name": "id", "in": "path", "description": "MCP server UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "mcps" ], "summary": "Update an existing MCP server entry (admin/manager only)", "operationId": "updateMcpServer", "parameters": [ { "name": "id", "in": "path", "description": "MCP server UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerRequest" } } }, "required": true }, "responses": { "200": { "description": "MCP server updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Not found" }, "409": { "description": "URL already exists" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/mcps/{id}": { "get": { "tags": [ "mcps" ], "summary": "Get a specific MCP instance by ID", "operationId": "getMcp", "parameters": [ { "name": "id", "in": "path", "description": "MCP instance UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mcp" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "MCP not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "mcps" ], "summary": "Update an MCP instance", "operationId": "updateMcp", "parameters": [ { "name": "id", "in": "path", "description": "MCP instance UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRequest" } } }, "required": true }, "responses": { "200": { "description": "MCP updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mcp" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "MCP not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "mcps" ], "summary": "Delete an MCP instance", "operationId": "deleteMcp", "parameters": [ { "name": "id", "in": "path", "description": "MCP instance UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "MCP deleted" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "MCP not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer": [] } ] } }, "/bodhi/v1/models": { "get": { "tags": [ "models" ], "summary": "List All Model Aliases", "description": "Retrieves paginated list of all configured model aliases including user-defined aliases, model aliases, and API provider aliases with filtering and sorting options. Requires any authenticated user (User level permissions or higher).", "operationId": "listAllModels", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of model aliases retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAliasResponse" }, "example": { "data": [ { "alias": "llama2:chat", "context_params": [ "--ctx_size", "4096" ], "filename": "llama-2-7b-chat.Q4_K_M.gguf", "repo": "TheBloke/Llama-2-7B-Chat-GGUF", "request_params": { "temperature": 0.7, "top_p": 0.95 }, "snapshot": "abc123", "source": "user" }, { "alias": "TheBloke/Llama-2-7B-Chat-GGUF:Q4_K_M", "filename": "llama-2-7b-chat.Q4_K_M.gguf", "repo": "TheBloke/Llama-2-7B-Chat-GGUF", "snapshot": "abc123", "source": "model" }, { "api_format": "openai", "base_url": "https://api.openai.com/v1", "created_at": "2024-01-01T00:00:00Z", "id": "openai-gpt4", "models": [ "gpt-4", "gpt-3.5-turbo" ], "source": "api", "updated_at": "2024-01-01T00:00:00Z" } ], "page": 1, "page_size": 10, "total": 3 } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/bodhi/v1/models/alias": { "post": { "tags": [ "models-alias" ], "summary": "Create Alias", "operationId": "models_alias_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasRequest" } } }, "required": true }, "responses": { "201": { "description": "Alias created succesfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/alias/{id}": { "put": { "tags": [ "models-alias" ], "summary": "Update Alias", "operationId": "models_alias_update", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the alias to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasRequest" } } }, "required": true }, "responses": { "200": { "description": "Alias updated succesfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] }, "delete": { "tags": [ "models-alias" ], "summary": "Delete a model alias by UUID", "operationId": "models_alias_destroy", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the alias to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alias deleted successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Alias not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/alias/{id}/copy": { "post": { "tags": [ "models-alias" ], "summary": "Copy a model alias", "operationId": "models_alias_copy", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the alias to copy", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyAliasRequest" } } }, "required": true }, "responses": { "201": { "description": "Alias copied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Source alias not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api": { "post": { "tags": [ "models-api" ], "summary": "Create a new API model configuration", "operationId": "createApiModel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiModelRequest" } } }, "required": true }, "responses": { "201": { "description": "API model created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "409": { "description": "Alias already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api/fetch-models": { "post": { "tags": [ "models-api" ], "summary": "Fetch available models from the API.", "operationId": "fetchApiModels", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchModelsRequest" } } }, "required": true }, "responses": { "200": { "description": "Available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchModelsResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api/formats": { "get": { "tags": [ "models-api" ], "summary": "Get Available API Formats", "description": "Retrieves list of supported API formats/protocols (e.g., OpenAI).", "operationId": "getApiFormats", "responses": { "200": { "description": "API formats retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFormatsResponse" }, "example": { "data": [ "openai" ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api/test": { "post": { "tags": [ "models-api" ], "summary": "Test API connectivity with a prompt.", "operationId": "testApiModel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestPromptRequest" } } }, "required": true }, "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestPromptResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api/{id}": { "get": { "tags": [ "models-api" ], "summary": "Get API Model Configuration", "description": "Retrieves detailed configuration for a specific API model alias by ID. API keys are masked for security unless explicitly requested.", "operationId": "getApiModel", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier for the API model alias", "required": true, "schema": { "type": "string" }, "example": "openai-gpt4" } ], "responses": { "200": { "description": "API model configuration retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAliasResponse" }, "example": { "api_format": "openai", "base_url": "https://api.openai.com/v1", "has_api_key": true, "id": "openai-gpt4", "models": [ "gpt-4" ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "API model with specified ID not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "entity_not_found", "message": "API model 'invalid-model' not found", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] }, "put": { "tags": [ "models-api" ], "summary": "Update an existing API model configuration", "operationId": "updateApiModel", "parameters": [ { "name": "id", "in": "path", "description": "API model ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiModelRequest" } } }, "required": true }, "responses": { "200": { "description": "API model updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "API model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] }, "delete": { "tags": [ "models-api" ], "summary": "Delete an API model configuration", "operationId": "deleteApiModel", "parameters": [ { "name": "id", "in": "path", "description": "API model ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "API model deleted" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "API model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/api/{id}/sync-models": { "post": { "tags": [ "models-api" ], "summary": "Sync Models to Cache", "description": "Synchronously fetches models from the external API and populates the cache. This ensures the cache is populated before returning. Primarily used for testing to avoid timing issues.", "operationId": "syncModels", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier for the API model alias", "required": true, "schema": { "type": "string" }, "example": "openai-gpt4" } ], "responses": { "200": { "description": "Models synced to cache successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAliasResponse" }, "example": { "api_format": "openai", "base_url": "https://api.openai.com/v1", "created_at": "2024-01-01T00:00:00Z", "forward_all_with_prefix": false, "has_api_key": true, "id": "openai-gpt4", "models": [ "gpt-4", "gpt-3.5-turbo", "gpt-4-turbo" ], "prefix": null, "updated_at": "2024-01-01T00:00:00Z" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "API model not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/files": { "get": { "tags": [ "models-files" ], "summary": "List Local Model Files", "description": "Retrieves paginated list of GGUF model files available in the local HuggingFace cache directory with metadata including repository, filename, snapshot ID, and file size. Requires any authenticated user (User level permissions or higher).", "operationId": "listModelFiles", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Local model files retrieved successfully from cache", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLocalModelResponse" }, "example": { "data": [ { "filename": "mistral-7b-instruct-v0.1.Q4_K_M.gguf", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "size": 4815162, "snapshot_id": "ab12cd34" } ], "page": 1, "page_size": 10, "total": 1 } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/bodhi/v1/models/files/pull": { "get": { "tags": [ "models-files" ], "summary": "List Model Download Requests", "description": "Retrieves paginated list of all model download requests with their current status, progress, and metadata. Includes both active downloads and completed/failed requests.", "operationId": "listDownloads", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model download requests retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDownloadResponse" }, "example": { "data": [ { "created_at": "2024-01-15T10:30:00Z", "filename": "mistral-7b-instruct-v0.1.Q4_K_M.gguf", "id": "download_123", "progress": 45.5, "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "status": "downloading", "updated_at": "2024-01-15T10:35:00Z" } ], "page": 1, "page_size": 10, "total": 1 } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] }, "post": { "tags": [ "models-files" ], "summary": "Start Model File Download", "description": "Initiates a new model file download from HuggingFace repository. Creates a download request that can be tracked for progress. Returns existing request if download is already in progress.", "operationId": "pullModelFile", "requestBody": { "description": "Model file download specification with repository and filename", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewDownloadRequest" }, "example": { "filename": "mistral-7b-instruct-v0.1.Q8_0.gguf", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF" } } }, "required": true }, "responses": { "200": { "description": "Existing download request found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" }, "example": { "created_at": "2024-11-10T04:52:06.786Z", "error": null, "filename": "mistral-7b-instruct-v0.1.Q8_0.gguf", "id": "550e8400-e29b-41d4-a716-446655440000", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "status": "pending", "updated_at": "2024-11-10T04:52:06.786Z" } } } }, "201": { "description": "Download request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" }, "example": { "created_at": "2024-11-10T04:52:06.786Z", "error": null, "filename": "mistral-7b-instruct-v0.1.Q8_0.gguf", "id": "550e8400-e29b-41d4-a716-446655440000", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "status": "pending", "updated_at": "2024-11-10T04:52:06.786Z" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/files/pull/{id}": { "get": { "tags": [ "models-files" ], "summary": "Get Download Request Status", "description": "Retrieves the current status and progress information for a specific model download request. Includes download progress, error details, and completion status.", "operationId": "getDownloadStatus", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the download request (UUID format)", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "responses": { "200": { "description": "Download request found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" }, "example": { "created_at": "2024-11-10T04:52:06.786Z", "error": null, "filename": "mistral-7b-instruct-v0.1.Q8_0.gguf", "id": "550e8400-e29b-41d4-a716-446655440000", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "status": "completed", "updated_at": "2024-01-20T12:00:10Z" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Download request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "db_error-item_not_found", "message": "item '550e8400-e29b-41d4-a716-446655440000' of type 'download_requests' not found in db", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_power_user" ] }, { "bearer_oauth_token": [ "scope_user_power_user" ] }, { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/refresh": { "post": { "tags": [ "models" ], "summary": "Refresh Model Metadata", "description": "Refresh metadata for models. Supports two modes via discriminated request body:\n\n- Bulk async: `{\"source\": \"all\"}` triggers background extraction for all local GGUF models (202 Accepted)\n\n- Single sync: `{\"source\": \"model\", \"repo\": \"...\", \"filename\": \"...\", \"snapshot\": \"...\"}` performs immediate extraction (200 OK)\n\nRequires PowerUser permissions.", "operationId": "refreshModelMetadata", "requestBody": { "description": "Refresh request - either bulk (source='all') or single model (source='model' with identifiers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" } } }, "required": true }, "responses": { "200": { "description": "Metadata refreshed successfully (sync mode)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelAliasResponse" } } } }, "202": { "description": "Metadata refresh queued in background (bulk mode)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" }, "example": { "num_queued": "all" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Model alias not found for specified repo/filename/snapshot" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/models/{id}": { "get": { "tags": [ "models" ], "summary": "Get Model Alias Details", "description": "Retrieves detailed information for a specific model alias by UUID. Requires any authenticated user (User level permissions or higher).", "operationId": "getAlias", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model alias details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAliasResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Alias not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "alias_not_found", "message": "Alias 'unknown:model' not found", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/bodhi/v1/queue": { "get": { "tags": [ "models" ], "summary": "Get Queue Status", "description": "Returns the current status of the metadata refresh queue. Requires PowerUser permissions.", "operationId": "getQueueStatus", "responses": { "200": { "description": "Queue status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueStatusResponse" }, "example": { "status": "idle" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/settings": { "get": { "tags": [ "settings" ], "summary": "List Application Settings", "description": "Retrieves all configurable application settings with their current values, default values, sources, and metadata including validation constraints.\n\n**Security Note:** Admin session authentication required for system configuration access.", "operationId": "listSettings", "responses": { "200": { "description": "Application settings retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SettingInfo" } }, "example": [ { "current_value": "info", "default_value": "warn", "key": "BODHI_LOG_LEVEL", "metadata": { "options": [ "error", "warn", "info", "debug", "trace" ], "type": "option" }, "source": "environment" }, { "current_value": 1135, "default_value": 1135, "key": "BODHI_PORT", "metadata": { "max": 65535, "min": 1025, "type": "number" }, "source": "default" } ] } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_admin" ] } ] } }, "/bodhi/v1/settings/{key}": { "put": { "tags": [ "settings" ], "summary": "Update Application Setting", "description": "Updates the value of a specific application setting. The new value is validated against the setting's constraints and persisted to the application database.\n\n**Security Note:** Admin session authentication required for system configuration changes.", "operationId": "updateSetting", "parameters": [ { "name": "key", "in": "path", "description": "Setting key identifier (e.g., BODHI_LOG_LEVEL, BODHI_PORT)", "required": true, "schema": { "type": "string" }, "example": "BODHI_LOG_LEVEL" } ], "requestBody": { "description": "New setting value", "content": { "application/json": { "schema": { "type": "object", "description": "Request to update a setting value", "required": [ "value" ], "properties": { "value": { "description": "New value for the setting (type depends on setting metadata)" } }, "example": { "value": "debug" } }, "example": { "value": "debug" } } }, "required": true }, "responses": { "200": { "description": "Setting updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingInfo" }, "example": { "current_value": "debug", "default_value": "warn", "key": "BODHI_LOG_LEVEL", "metadata": { "options": [ "error", "warn", "info", "debug", "trace" ], "type": "option" }, "source": "database" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Setting not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "settings_route_error-not_found", "message": "Setting not found: INVALID_KEY", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_admin" ] } ] }, "delete": { "tags": [ "settings" ], "summary": "Reset Setting to Default", "description": "Resets a specific application setting to its default value by removing any custom overrides. Some critical settings like BODHI_HOME cannot be reset.\n\n**Security Note:** Admin session authentication required.", "operationId": "deleteSetting", "parameters": [ { "name": "key", "in": "path", "description": "Setting key identifier to reset to default value", "required": true, "schema": { "type": "string" }, "example": "BODHI_LOG_LEVEL" } ], "responses": { "200": { "description": "Setting reset to default successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingInfo" }, "example": { "current_value": "warn", "default_value": "warn", "key": "BODHI_LOG_LEVEL", "metadata": { "options": [ "error", "warn", "info", "debug", "trace" ], "type": "option" }, "source": "default" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Setting not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "settings_route_error-not_found", "message": "Setting not found: INVALID_KEY", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_admin" ] } ] } }, "/bodhi/v1/setup": { "post": { "tags": [ "setup" ], "summary": "Setup Application", "description": "Initializes the application with authentication configuration and registers with the auth server", "operationId": "setupApp", "requestBody": { "description": "Application setup configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupRequest" }, "example": { "description": "My personal AI server", "name": "My Bodhi Server" } } }, "required": true }, "responses": { "200": { "description": "Application setup completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupResponse" }, "example": { "status": "resource_admin" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } } } }, "/bodhi/v1/tenants": { "get": { "tags": [ "tenants" ], "summary": "List Tenants", "description": "Lists all tenants visible to the authenticated dashboard user. Each tenant includes whether it is currently active and whether the user has a valid session for it.", "operationId": "tenantsList", "responses": { "200": { "description": "List of tenants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantListResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] }, "post": { "tags": [ "tenants" ], "summary": "Create Tenant", "description": "Creates a new tenant (Keycloak client) via the Bodhi SPI and registers it locally.", "operationId": "tenantsCreate", "requestBody": { "description": "Tenant creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } }, "required": true }, "responses": { "201": { "description": "Tenant created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/tenants/{client_id}/activate": { "post": { "tags": [ "tenants" ], "summary": "Activate Tenant", "description": "Sets the given tenant as the active tenant for the current session. The user must already be logged into this tenant.", "operationId": "tenantsActivate", "parameters": [ { "name": "client_id", "in": "path", "description": "The client_id of the tenant to activate", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant activated successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/tokens": { "get": { "tags": [ "api-keys" ], "summary": "List API Tokens", "description": "Retrieves paginated list of API tokens owned by the current user. Includes token metadata but not the actual token values for security.\n\n**Security Note:** Session-only authentication required to prevent information disclosure via tokens.", "operationId": "listApiTokens", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based indexing)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "page_size", "in": "query", "description": "Number of items to return per page (maximum 100)", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort", "in": "query", "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "required": false, "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of API tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTokenResponse" }, "example": { "data": [ { "created_at": "2024-11-10T04:52:06.786Z", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Development Token", "status": "active", "token_id": "jwt-token-id-1", "updated_at": "2024-11-10T04:52:06.786Z", "user_id": "user@email.com" }, { "created_at": "2024-11-10T04:52:06.786Z", "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Test Token", "status": "inactive", "token_id": "jwt-token-id-2", "updated_at": "2024-11-10T04:52:06.786Z", "user_id": "user@email.com" } ], "page": 1, "page_size": 10, "total": 2 } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_power_user" ] } ] }, "post": { "tags": [ "api-keys" ], "summary": "Create API Token", "description": "Creates a new API token for programmatic access to the API. The token can be used for bearer authentication in API requests. Tokens are scoped based on user role: User role receives scope_token_user (basic access), while Admin/Manager/PowerUser roles receive scope_token_power_user (administrative access).\n\n**Security Note:** Session-only authentication required to prevent token-based privilege escalation.", "operationId": "createApiToken", "requestBody": { "description": "API token creation parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenRequest" }, "example": { "name": "My Integration Token", "scopes": [ "scope_token_user" ] } } }, "required": true }, "responses": { "201": { "description": "API token created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreated" }, "example": { "token": "bodhiapp_1234567890abcdef" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/tokens/{id}": { "put": { "tags": [ "api-keys" ], "summary": "Update API Token", "description": "Updates the name and status of an existing API token. Only the token owner can update their tokens. Token values cannot be changed after creation.\n\n**Security Note:** Session-only authentication required to prevent token-based privilege escalation.", "operationId": "updateApiToken", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the API token to update", "required": true, "schema": { "type": "string" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "description": "Token update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTokenRequest" }, "example": { "name": "Updated Token Name", "status": "inactive" } } }, "required": true }, "responses": { "200": { "description": "Token updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenDetail" }, "example": { "created_at": "2024-11-10T04:52:06.786Z", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Updated Token Name", "status": "inactive", "token_id": "jwt-token-id-1", "updated_at": "2024-11-10T04:52:06.786Z", "user_id": "auth0|123456789" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "entity_error-not_found", "message": "Token not found", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_power_user" ] } ] } }, "/bodhi/v1/user": { "get": { "tags": [ "auth" ], "summary": "Get Current User Information", "description": "Retrieves information about the currently authenticated user. This endpoint supports optional authentication - returns `logged_out` status if not authenticated, or user details with roles/scopes if authenticated via any method (session, API token, or OAuth exchange). Includes `dashboard` object when the user has an active dashboard session.", "operationId": "getCurrentUser", "responses": { "200": { "description": "User information (authenticated or not)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoEnvelope" }, "examples": { "authenticated": { "summary": "Fully authenticated with dashboard", "value": { "auth_status": "logged_in", "dashboard": { "first_name": "Test", "last_name": "User", "user_id": "550e8400-e29b-41d4-a716-446655440000", "username": "user@example.com" }, "role": "resource_admin", "user_id": "550e8400-e29b-41d4-a716-446655440000", "username": "user@example.com" } }, "dashboard_only": { "summary": "Dashboard session only (no tenant login)", "value": { "auth_status": "logged_out", "dashboard": { "first_name": "Test", "last_name": "User", "user_id": "550e8400-e29b-41d4-a716-446655440000", "username": "user@example.com" } } }, "unauthenticated": { "summary": "Unauthenticated request", "value": { "auth_status": "logged_out" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/user/request-access": { "post": { "tags": [ "auth" ], "summary": "Request User Access", "description": "Authenticated users without roles can request access to the system. Only one pending request is allowed per user.", "operationId": "requestUserAccess", "responses": { "201": { "description": "Access request created successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "409": { "description": "Pending request already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "422": { "description": "User already has role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/user/request-status": { "get": { "tags": [ "auth" ], "summary": "Get Access Request Status", "description": "Check the status of the current user's access request.", "operationId": "getUserAccessStatus", "responses": { "200": { "description": "Request status retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAccessStatusResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ {}, { "bearer_api_token": [] }, { "bearer_oauth_token": [] }, { "session_auth": [] } ] } }, "/bodhi/v1/users": { "get": { "tags": [ "auth" ], "summary": "List users", "description": "List all users with roles and status information. Available to managers and admins.", "operationId": "listUsers", "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 1 }, { "name": "page_size", "in": "query", "description": "Number of users per page", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 10 } ], "responses": { "200": { "description": "Users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/users/{user_id}": { "delete": { "tags": [ "auth" ], "summary": "Remove user access", "description": "Remove a user's access to the application. Only managers or above can remove users.", "operationId": "removeUser", "parameters": [ { "name": "user_id", "in": "path", "description": "User ID to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User removed successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/bodhi/v1/users/{user_id}/role": { "put": { "tags": [ "auth" ], "summary": "Change user role", "description": "Assign a new role to a user. Admins can assign any role, managers can assign user/power_user/manager roles.", "operationId": "changeUserRole", "parameters": [ { "name": "user_id", "in": "path", "description": "User ID to change role for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role changed successfully" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "session_auth": [ "resource_manager" ] } ] } }, "/health": { "get": { "tags": [ "system" ], "summary": "Health Check", "description": "Comprehensive health check to verify all application components are operational", "operationId": "healthCheck", "responses": { "200": { "description": "Application is healthy and fully operational", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" }, "example": { "message": "pong" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } } } }, "/ping": { "get": { "tags": [ "system" ], "summary": "Ping Server", "description": "Simple connectivity check to verify the server is responding", "operationId": "pingServer", "responses": { "200": { "description": "Server is responding normally", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" }, "example": { "message": "pong" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "openai" ], "summary": "Create Chat Completion (OpenAI Compatible)", "description": "Creates a chat completion response using the specified model. Supports both streaming and non-streaming responses. Fully compatible with OpenAI's chat completions API format.", "operationId": "createChatCompletion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionRequest" }, "example": { "max_tokens": 100, "messages": [ { "content": "You are a helpful assistant.", "role": "system" }, { "content": "Hello!", "role": "user" } ], "model": "llama2:chat", "stream": false, "temperature": 0.7 } } }, "required": true }, "responses": { "200": { "description": "Chat completion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" }, "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "Hello! How can I help you today?", "role": "assistant" } } ], "created": 1677610602, "id": "chatcmpl-123", "model": "llama2:chat", "object": "chat.completion", "usage": { "completion_tokens": 10, "prompt_tokens": 20, "total_tokens": 30 } } } } }, "201": { "description": "Chat completion stream, the status is 200, using 201 to avoid OpenAPI format limitation.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "No-cache directive" } }, "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionStreamResponse" }, "example": { "choices": [ { "delta": { "content": "Hello" }, "finish_reason": null, "index": 0 } ], "created": 1694268190, "id": "chatcmpl-123", "model": "llama2:chat", "object": "chat.completion.chunk" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/embeddings": { "post": { "tags": [ "openai" ], "summary": "Create Embeddings (OpenAI Compatible)", "description": "Creates embeddings for the input text using the specified model. Fully compatible with OpenAI's embeddings API format.", "operationId": "createEmbedding", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingRequest" }, "example": { "input": "The quick brown fox jumps over the lazy dog", "model": "text-embedding-model" } } }, "required": true }, "responses": { "200": { "description": "Embedding response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingResponse" }, "example": { "data": [ { "embedding": [ 0.1, 0.2, 0.3 ], "index": 0, "object": "embedding" } ], "model": "text-embedding-model", "object": "list", "usage": { "prompt_tokens": 8, "total_tokens": 8 } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/models": { "get": { "tags": [ "openai" ], "summary": "List Available Models (OpenAI Compatible)", "description": "Returns a list of all available models in OpenAI API compatible format. Includes user aliases, model aliases, and API provider aliases that can be used with the chat completions endpoint.", "operationId": "listModels", "responses": { "200": { "description": "List of available models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelResponse" }, "example": { "data": [ { "created": 1677610602, "id": "llama2:chat", "object": "model", "owned_by": "bodhi" }, { "created": 1677610602, "id": "mistral:instruct", "object": "model", "owned_by": "bodhi" } ], "object": "list" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/models/{id}": { "get": { "tags": [ "openai" ], "summary": "Get Model Details (OpenAI Compatible)", "description": "Retrieves details for a specific model by ID in OpenAI API compatible format. The model ID can be a user alias, model alias, or API provider alias.", "operationId": "getModel", "parameters": [ { "name": "id", "in": "path", "description": "Model identifier - can be user alias (e.g., 'llama2:chat'), model alias, or API provider alias", "required": true, "schema": { "type": "string" }, "example": "llama2:chat" } ], "responses": { "200": { "description": "Model details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "example": { "created": 1677610602, "id": "llama2:chat", "object": "model", "owned_by": "system" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "404": { "description": "Model not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" }, "example": { "error": { "code": "model_not_found", "message": "Model 'unknown:model' not found", "type": "not_found_error" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/responses": { "post": { "tags": [ "responses" ], "summary": "Create Response (OpenAI Responses API)", "description": "Creates a model response using the Responses API format. Proxied to the upstream provider. Supports both streaming and non-streaming responses.", "operationId": "createResponse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" } } }, "required": true }, "responses": { "200": { "description": "Response created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Response stream (actual status is 200, using 201 to avoid OpenAPI limitation).", "content": { "text/event-stream": { "schema": {} } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/responses/{response_id}": { "get": { "tags": [ "responses" ], "summary": "Retrieve Response", "description": "Retrieves a previously created response by ID. Note: `model` query parameter is required for multi-provider routing (not part of upstream OpenAI API).", "operationId": "getResponse", "parameters": [ { "name": "response_id", "in": "path", "description": "The response ID", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Model name for routing to the correct upstream provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] }, "delete": { "tags": [ "responses" ], "summary": "Delete Response", "description": "Deletes a stored response by ID. Note: `model` query parameter is required for multi-provider routing (not part of upstream OpenAI API).", "operationId": "deleteResponse", "parameters": [ { "name": "response_id", "in": "path", "description": "The response ID", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Model name for routing to the correct upstream provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response deleted" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/responses/{response_id}/cancel": { "post": { "tags": [ "responses" ], "summary": "Cancel Response", "description": "Cancels a background response. Note: `model` query parameter is required for multi-provider routing (not part of upstream OpenAI API).", "operationId": "cancelResponse", "parameters": [ { "name": "response_id", "in": "path", "description": "The response ID", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Model name for routing to the correct upstream provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } }, "/v1/responses/{response_id}/input_items": { "get": { "tags": [ "responses" ], "summary": "List Response Input Items", "description": "Lists input items for a given response. Note: `model` query parameter is required for multi-provider routing (not part of upstream OpenAI API).", "operationId": "listResponseInputItems", "parameters": [ { "name": "response_id", "in": "path", "description": "The response ID", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Model name for routing to the correct upstream provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Input items retrieved" }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIApiError" } } } } }, "security": [ { "bearer_api_token": [ "scope_token_user" ] }, { "bearer_oauth_token": [ "scope_user_user" ] }, { "session_auth": [ "resource_user" ] } ] } } }, "components": { "schemas": { "AccessRequestActionResponse": { "type": "object", "required": [ "status", "flow_type" ], "properties": { "status": { "$ref": "#/components/schemas/AppAccessRequestStatus", "description": "Updated status after action" }, "flow_type": { "$ref": "#/components/schemas/FlowType", "description": "Flow type of the access request" }, "redirect_url": { "type": [ "string", "null" ], "description": "Redirect URL (present for redirect flow)" } } }, "AccessRequestReviewResponse": { "type": "object", "required": [ "id", "app_client_id", "flow_type", "status", "requested_role", "requested" ], "properties": { "id": { "type": "string", "description": "Access request ID" }, "app_client_id": { "type": "string", "description": "App client ID" }, "app_name": { "type": [ "string", "null" ], "description": "App name from KC (if available)" }, "app_description": { "type": [ "string", "null" ], "description": "App description from KC (if available)" }, "flow_type": { "$ref": "#/components/schemas/FlowType", "description": "Flow type: \"redirect\" or \"popup\"" }, "status": { "$ref": "#/components/schemas/AppAccessRequestStatus", "description": "Current status" }, "requested_role": { "type": "string", "description": "Role requested by the app" }, "requested": { "$ref": "#/components/schemas/RequestedResources", "description": "Resources requested" }, "mcps_info": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerReviewInfo" }, "description": "MCP server information with user instances" } } }, "AccessRequestStatusResponse": { "type": "object", "required": [ "id", "status", "requested_role" ], "properties": { "id": { "type": "string", "description": "Access request ID" }, "status": { "$ref": "#/components/schemas/AppAccessRequestStatus", "description": "Current status: \"draft\", \"approved\", \"denied\", \"failed\"" }, "requested_role": { "$ref": "#/components/schemas/UserScope", "description": "Role requested by the app" }, "approved_role": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UserScope", "description": "Role approved (present when approved)" } ] }, "access_request_scope": { "type": [ "string", "null" ], "description": "Access request scope (present when user-approved with tools)" } }, "example": { "access_request_scope": "scope_access_request:550e8400-e29b-41d4-a716-446655440000", "approved_role": "scope_user_user", "id": "550e8400-e29b-41d4-a716-446655440000", "requested_role": "scope_user_user", "status": "approved" } }, "Alias": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/UserAlias", "description": "User-defined local model (source: \"user\")" }, { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "user" ] } } } ], "description": "User-defined local model (source: \"user\")" }, { "allOf": [ { "$ref": "#/components/schemas/ModelAlias", "description": "Auto-discovered local model (source: \"model\")" }, { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "model" ] } } } ], "description": "Auto-discovered local model (source: \"model\")" }, { "allOf": [ { "$ref": "#/components/schemas/ApiAlias", "description": "Remote API model (source: \"api\")" }, { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "api" ] } } } ], "description": "Remote API model (source: \"api\")" } ], "description": "Flat enum representing all types of model aliases\nEach variant is identified by the source field" }, "AliasResponse": { "oneOf": [ { "$ref": "#/components/schemas/UserAliasResponse", "description": "User-defined local model (source: \"user\")" }, { "$ref": "#/components/schemas/ModelAliasResponse", "description": "Auto-discovered local model (source: \"model\")" }, { "$ref": "#/components/schemas/ApiAliasResponse", "description": "Remote API model (source: \"api\")" } ], "description": "Response envelope for model aliases - hides internal implementation details\nUses untagged serialization - each variant has its own \"source\" field" }, "Annotation": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/FileCitationBody", "description": "A citation to a file." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_citation" ] } } } ], "description": "A citation to a file." }, { "allOf": [ { "$ref": "#/components/schemas/UrlCitationBody", "description": "A citation for a web resource used to generate a model response." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "url_citation" ] } } } ], "description": "A citation for a web resource used to generate a model response." }, { "allOf": [ { "$ref": "#/components/schemas/ContainerFileCitationBody", "description": "A citation for a container file used to generate a model response." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_file_citation" ] } } } ], "description": "A citation for a container file used to generate a model response." }, { "allOf": [ { "$ref": "#/components/schemas/FilePath", "description": "A path to a file." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_path" ] } } } ], "description": "A path to a file." } ], "description": "An annotation that applies to a span of output text." }, "ApiAlias": { "type": "object", "required": [ "id", "api_format", "base_url", "models", "forward_all_with_prefix", "models_cache", "cache_fetched_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "api_format": { "$ref": "#/components/schemas/ApiFormat" }, "base_url": { "type": "string" }, "models": { "$ref": "#/components/schemas/JsonVec" }, "prefix": { "type": [ "string", "null" ] }, "forward_all_with_prefix": { "type": "boolean" }, "models_cache": { "$ref": "#/components/schemas/JsonVec" }, "cache_fetched_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ApiAliasResponse": { "type": "object", "description": "API response for API model aliases - hides internal cache fields", "required": [ "source", "id", "api_format", "base_url", "has_api_key", "models", "forward_all_with_prefix", "created_at", "updated_at" ], "properties": { "source": { "type": "string" }, "id": { "type": "string" }, "api_format": { "$ref": "#/components/schemas/ApiFormat" }, "base_url": { "type": "string" }, "has_api_key": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "string" }, "description": "Models available through this alias (merged from cache for forward_all)" }, "prefix": { "type": [ "string", "null" ] }, "forward_all_with_prefix": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ApiFormat": { "type": "string", "description": "API format/protocol specification", "enum": [ "openai", "openai_responses", "placeholder" ] }, "ApiFormatsResponse": { "type": "object", "description": "Response containing available API formats", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiFormat" } } }, "example": { "data": [ "openai" ] } }, "ApiKey": { "type": [ "string", "null" ], "description": "Validated API key wrapper - validates length when Some, allows None for public APIs" }, "ApiKeyUpdate": { "oneOf": [ { "type": "object", "description": "Keep the existing API key unchanged", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "keep" ] } } }, { "type": "object", "description": "Set a new API key (or add one if none exists) - ApiKey validates length", "required": [ "value", "action" ], "properties": { "value": { "$ref": "#/components/schemas/ApiKey", "description": "Set a new API key (or add one if none exists) - ApiKey validates length" }, "action": { "type": "string", "enum": [ "set" ] } } } ], "description": "Represents an API key update operation for API model aliases." }, "ApiModelRequest": { "type": "object", "description": "Input request for creating or updating an API model configuration.", "required": [ "api_format", "base_url", "models" ], "properties": { "api_format": { "$ref": "#/components/schemas/ApiFormat", "description": "API format/protocol (e.g., \"openai\")" }, "base_url": { "type": "string", "description": "API base URL" }, "api_key": { "$ref": "#/components/schemas/ApiKeyUpdate", "description": "API key update action (Keep/Set with Some or None)" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of available models" }, "prefix": { "type": [ "string", "null" ], "description": "Optional prefix for model namespacing (e.g., \"azure/\" for \"azure/gpt-4\")" }, "forward_all_with_prefix": { "type": "boolean", "description": "Whether to forward all requests with this prefix (true) or only selected models (false)" } }, "example": { "api_format": "openai", "api_key": { "action": "set", "value": "sk-..." }, "base_url": "https://api.openai.com/v1", "models": [ "gpt-4", "gpt-3.5-turbo" ], "prefix": "openai" } }, "AppAccessRequestStatus": { "type": "string", "enum": [ "draft", "approved", "denied", "failed", "expired" ] }, "AppInfo": { "type": "object", "description": "Application information and status", "required": [ "version", "commit_sha", "status", "deployment", "url" ], "properties": { "version": { "type": "string", "description": "Application version number (semantic versioning)", "example": "0.1.0" }, "commit_sha": { "type": "string", "description": "Git commit SHA of the build", "example": "abc1234" }, "status": { "$ref": "#/components/schemas/AppStatus", "description": "Current application setup and operational status" }, "deployment": { "$ref": "#/components/schemas/DeploymentMode", "description": "Deployment mode: \"standalone\" or \"multi_tenant\"" }, "client_id": { "type": [ "string", "null" ], "description": "Active tenant's OAuth client_id (present when authenticated with an active tenant)", "example": "my-client-id" }, "url": { "type": "string", "description": "Public URL of the server", "example": "https://example.com" } }, "example": { "client_id": "my-client-id", "commit_sha": "abc1234", "deployment": "standalone", "status": "ready", "url": "https://example.com", "version": "0.1.0" } }, "AppRole": { "oneOf": [ { "$ref": "#/components/schemas/ResourceRole" }, { "$ref": "#/components/schemas/TokenScope" }, { "$ref": "#/components/schemas/UserScope" } ] }, "AppStatus": { "type": "string", "enum": [ "setup", "ready", "resource_admin" ], "example": "ready" }, "ApplyPatchCallOutputStatus": { "type": "string", "description": "Outcome values reported for apply_patch tool call outputs.", "enum": [ "completed", "failed" ] }, "ApplyPatchCallOutputStatusParam": { "type": "string", "description": "Outcome values reported for apply_patch tool call outputs.", "enum": [ "completed", "failed" ] }, "ApplyPatchCallStatus": { "type": "string", "description": "Status values reported for apply_patch tool calls.", "enum": [ "in_progress", "completed" ] }, "ApplyPatchCallStatusParam": { "type": "string", "description": "Status values reported for apply_patch tool calls.", "enum": [ "in_progress", "completed" ] }, "ApplyPatchCreateFileOperation": { "type": "object", "description": "Instruction describing how to create a file via the apply_patch tool.", "required": [ "path", "diff" ], "properties": { "path": { "type": "string", "description": "Path of the file to create." }, "diff": { "type": "string", "description": "Diff to apply." } } }, "ApplyPatchCreateFileOperationParam": { "type": "object", "description": "Instruction for creating a new file via the apply_patch tool.", "required": [ "path", "diff" ], "properties": { "path": { "type": "string", "description": "Path of the file to create relative to the workspace root." }, "diff": { "type": "string", "description": "Unified diff content to apply when creating the file." } } }, "ApplyPatchDeleteFileOperation": { "type": "object", "description": "Instruction describing how to delete a file via the apply_patch tool.", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Path of the file to delete." } } }, "ApplyPatchDeleteFileOperationParam": { "type": "object", "description": "Instruction for deleting an existing file via the apply_patch tool.", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "Path of the file to delete relative to the workspace root." } } }, "ApplyPatchOperation": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchCreateFileOperation" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "create_file" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchDeleteFileOperation" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "delete_file" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchUpdateFileOperation" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "update_file" ] } } } ] } ], "description": "One of the create_file, delete_file, or update_file operations applied via apply_patch." }, "ApplyPatchOperationParam": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchCreateFileOperationParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "create_file" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchDeleteFileOperationParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "delete_file" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchUpdateFileOperationParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "update_file" ] } } } ] } ], "description": "One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool." }, "ApplyPatchToolCall": { "type": "object", "description": "A tool call that applies file diffs by creating, deleting, or updating files.", "required": [ "id", "call_id", "status", "operation" ], "properties": { "id": { "type": "string", "description": "The unique ID of the apply patch tool call. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the apply patch tool call generated by the model." }, "status": { "$ref": "#/components/schemas/ApplyPatchCallStatus", "description": "The status of the apply patch tool call. One of `in_progress` or `completed`." }, "operation": { "$ref": "#/components/schemas/ApplyPatchOperation", "description": "One of the create_file, delete_file, or update_file operations applied via apply_patch." }, "created_by": { "type": [ "string", "null" ], "description": "The ID of the entity that created this tool call." } } }, "ApplyPatchToolCallItemParam": { "type": "object", "description": "A tool call representing a request to create, delete, or update files using diff patches.", "required": [ "call_id", "status", "operation" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of the apply patch tool call. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the apply patch tool call generated by the model." }, "status": { "$ref": "#/components/schemas/ApplyPatchCallStatusParam", "description": "The status of the apply patch tool call. One of `in_progress` or `completed`." }, "operation": { "$ref": "#/components/schemas/ApplyPatchOperationParam", "description": "The specific create, delete, or update instruction for the apply_patch tool call." } } }, "ApplyPatchToolCallOutput": { "type": "object", "description": "The output emitted by an apply patch tool call.", "required": [ "id", "call_id", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the apply patch tool call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the apply patch tool call generated by the model." }, "status": { "$ref": "#/components/schemas/ApplyPatchCallOutputStatus", "description": "The status of the apply patch tool call output. One of `completed` or `failed`." }, "output": { "type": [ "string", "null" ], "description": "Optional textual output returned by the apply patch tool." }, "created_by": { "type": [ "string", "null" ], "description": "The ID of the entity that created this tool call output." } } }, "ApplyPatchToolCallOutputItemParam": { "type": "object", "description": "The streamed output emitted by an apply patch tool call.", "required": [ "call_id", "status" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of the apply patch tool call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the apply patch tool call generated by the model." }, "status": { "$ref": "#/components/schemas/ApplyPatchCallOutputStatusParam", "description": "The status of the apply patch tool call output. One of `completed` or `failed`." }, "output": { "type": [ "string", "null" ], "description": "Optional human-readable log text from the apply patch tool (e.g., patch results or errors)." } } }, "ApplyPatchUpdateFileOperation": { "type": "object", "description": "Instruction describing how to update a file via the apply_patch tool.", "required": [ "path", "diff" ], "properties": { "path": { "type": "string", "description": "Path of the file to update." }, "diff": { "type": "string", "description": "Diff to apply." } } }, "ApplyPatchUpdateFileOperationParam": { "type": "object", "description": "Instruction for updating an existing file via the apply_patch tool.", "required": [ "path", "diff" ], "properties": { "path": { "type": "string", "description": "Path of the file to update relative to the workspace root." }, "diff": { "type": "string", "description": "Unified diff content to apply to the existing file." } } }, "ApprovalStatus": { "type": "string", "enum": [ "approved", "denied" ] }, "ApproveAccessRequest": { "type": "object", "description": "Request for approving an app access request", "required": [ "approved_role", "approved" ], "properties": { "approved_role": { "$ref": "#/components/schemas/UserScope", "description": "Role to grant for the approved request (scope_user_user or scope_user_power_user)" }, "approved": { "$ref": "#/components/schemas/ApprovedResources", "description": "Approved resources with selections" } }, "example": { "approved": { "mcps": [ { "instance": { "id": "instance-uuid", "path": "/bodhi/v1/apps/mcps/instance-uuid/mcp" }, "status": "approved", "url": "https://mcp.deepwiki.com/mcp" } ], "version": "1" }, "approved_role": "scope_user_user" } }, "ApproveUserAccessRequest": { "type": "object", "description": "Request body for approving access with role assignment", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/ResourceRole", "description": "Role to assign to the user" } }, "example": { "role": "resource_user" } }, "ApprovedResources": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ApprovedResourcesV1" }, { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "enum": [ "1" ] } } } ] } ], "description": "Versioned envelope for approved resources.\nThe `version` tag is mandatory and must match the corresponding `RequestedResources` version." }, "ApprovedResourcesV1": { "type": "object", "properties": { "mcps": { "type": "array", "items": { "$ref": "#/components/schemas/McpApproval" } } } }, "AssistantRole": { "type": "string", "description": "The role for an output message - always `assistant`.\nThis type ensures type safety by only allowing the assistant role.", "enum": [ "assistant" ] }, "AuthCallbackRequest": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "OAuth authorization code from successful authentication (required for success flow)", "example": "auth_code_123" }, "state": { "type": [ "string", "null" ], "description": "OAuth state parameter for CSRF protection (must match initiated request)", "example": "random_state_456" }, "error": { "type": [ "string", "null" ], "description": "OAuth error code if authentication failed (e.g., \"access_denied\")", "example": "access_denied" }, "error_description": { "type": [ "string", "null" ], "description": "Human-readable OAuth error description if authentication failed", "example": "The user denied the request" } }, "additionalProperties": { "type": "string", "description": "Additional OAuth 2.1 parameters sent by the authorization server", "additionalProperties": true }, "example": { "code": "auth_code_123", "state": "random_state_456" } }, "AuthInitiateRequest": { "type": "object", "description": "Request body for initiating OAuth authentication", "required": [ "client_id" ], "properties": { "client_id": { "type": "string", "description": "The OAuth client_id of the tenant to authenticate with", "example": "my-client-id" } }, "example": { "client_id": "my-client-id" } }, "Billing": { "type": "object", "required": [ "payer" ], "properties": { "payer": { "type": "string" } } }, "ChangeRoleRequest": { "type": "object", "description": "Change user role request", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/ResourceRole", "description": "Role to assign to the user" } } }, "ChatChoice": { "type": "object", "required": [ "index", "message" ], "properties": { "index": { "type": "integer", "format": "int32", "description": "The index of the choice in the list of choices.", "minimum": 0 }, "message": { "$ref": "#/components/schemas/ChatCompletionResponseMessage" }, "finish_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FinishReason", "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,\n`length` if the maximum number of tokens specified in the request was reached,\n`content_filter` if content was omitted due to a flag from our content filters,\n`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function." } ] }, "logprobs": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatChoiceLogprobs", "description": "Log probability information for the choice." } ] } } }, "ChatChoiceLogprobs": { "type": "object", "properties": { "content": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "description": "A list of message content tokens with log probability information." }, "refusal": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" } } } }, "ChatChoiceStream": { "type": "object", "required": [ "index", "delta" ], "properties": { "index": { "type": "integer", "format": "int32", "description": "The index of the choice in the list of choices.", "minimum": 0 }, "delta": { "$ref": "#/components/schemas/ChatCompletionStreamResponseDelta" }, "finish_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FinishReason", "description": "The reason the model stopped generating tokens. This will be\n`stop` if the model hit a natural stop point or a provided\nstop sequence,\n\n`length` if the maximum number of tokens specified in the\nrequest was reached,\n`content_filter` if content was omitted due to a flag from our\ncontent filters,\n`tool_calls` if the model called a tool, or `function_call`\n(deprecated) if the model called a function." } ] }, "logprobs": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatChoiceLogprobs", "description": "Log probability information for the choice." } ] } } }, "ChatCompletionAllowedTools": { "type": "object", "required": [ "mode", "tools" ], "properties": { "mode": { "$ref": "#/components/schemas/ToolChoiceAllowedMode", "description": "Constrains the tools available to the model to a pre-defined set.\n\n`auto` allows the model to pick from among the allowed tools and generate a\nmessage.\n\n`required` requires the model to call one or more of the allowed tools." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "A list of tool definitions that the model should be allowed to call.\n\nFor the Chat Completions API, the list of tool definitions might look like:\n```json\n[\n { \"type\": \"function\", \"function\": { \"name\": \"get_weather\" } },\n { \"type\": \"function\", \"function\": { \"name\": \"get_time\" } }\n]\n```" } } }, "ChatCompletionAllowedToolsChoice": { "type": "object", "required": [ "allowed_tools" ], "properties": { "allowed_tools": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionAllowedTools" } } } }, "ChatCompletionAudio": { "type": "object", "required": [ "voice", "format" ], "properties": { "voice": { "$ref": "#/components/schemas/ChatCompletionAudioVoice", "description": "The voice the model uses to respond. Supported built-in voices are `alloy`, `ash`,\n`ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`, `marin`, and `cedar`." }, "format": { "$ref": "#/components/schemas/ChatCompletionAudioFormat", "description": "Specifies the output audio format. Must be one of `wav`, `aac`, `mp3`, `flac`, `opus`, or `pcm16`." } } }, "ChatCompletionAudioFormat": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] }, "ChatCompletionAudioVoice": { "oneOf": [ { "type": "string", "enum": [ "alloy" ] }, { "type": "string", "enum": [ "ash" ] }, { "type": "string", "enum": [ "ballad" ] }, { "type": "string", "enum": [ "coral" ] }, { "type": "string", "enum": [ "echo" ] }, { "type": "string", "enum": [ "fable" ] }, { "type": "string", "enum": [ "nova" ] }, { "type": "string", "enum": [ "onyx" ] }, { "type": "string", "enum": [ "sage" ] }, { "type": "string", "enum": [ "shimmer" ] }, { "type": "object", "required": [ "other" ], "properties": { "other": { "type": "string" } } } ] }, "ChatCompletionFunctionCall": { "oneOf": [ { "type": "string", "description": "The model does not call a function, and responds to the end-user.", "enum": [ "none" ] }, { "type": "string", "description": "The model can pick between an end-user or calling a function.", "enum": [ "auto" ] }, { "type": "object", "description": "Forces the model to call the specified function.", "required": [ "Function" ], "properties": { "Function": { "type": "object", "description": "Forces the model to call the specified function.", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } ] }, "ChatCompletionFunctions": { "type": "object", "required": [ "name", "parameters" ], "properties": { "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "description": { "type": [ "string", "null" ], "description": "A description of what the function does, used by the model to choose when and how to call the function." }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/text-generation/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.\n\nOmitting `parameters` defines a function with an empty parameter list." } } }, "ChatCompletionMessageCustomToolCall": { "type": "object", "required": [ "id", "custom_tool" ], "properties": { "id": { "type": "string", "description": "The ID of the tool call." }, "custom_tool": { "$ref": "#/components/schemas/CustomTool", "description": "The custom tool that the model called." } } }, "ChatCompletionMessageToolCall": { "type": "object", "required": [ "id", "function" ], "properties": { "id": { "type": "string", "description": "The ID of the tool call." }, "function": { "$ref": "#/components/schemas/FunctionCall", "description": "The function that the model called." } } }, "ChatCompletionMessageToolCallChunk": { "type": "object", "required": [ "index" ], "properties": { "index": { "type": "integer", "format": "int32", "minimum": 0 }, "id": { "type": [ "string", "null" ], "description": "The ID of the tool call." }, "type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionType", "description": "The type of the tool. Currently, only `function` is supported." } ] }, "function": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionCallStream" } ] } } }, "ChatCompletionMessageToolCalls": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageToolCall" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageCustomToolCall" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ] } ] }, "ChatCompletionNamedToolChoice": { "type": "object", "description": "Specifies a tool the model should use. Use to force the model to call a specific function.", "required": [ "function" ], "properties": { "function": { "$ref": "#/components/schemas/FunctionName" } } }, "ChatCompletionNamedToolChoiceCustom": { "type": "object", "required": [ "custom" ], "properties": { "custom": { "$ref": "#/components/schemas/CustomName" } } }, "ChatCompletionRequestAssistantMessage": { "type": "object", "properties": { "content": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessageContent", "description": "The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified." } ] }, "refusal": { "type": [ "string", "null" ], "description": "The refusal message by the assistant." }, "name": { "type": [ "string", "null" ], "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." }, "audio": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessageAudio", "description": "Data about a previous audio response from the model.\n[Learn more](https://platform.openai.com/docs/guides/audio)." } ] }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionMessageToolCalls" } }, "function_call": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionCall", "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model." } ] } } }, "ChatCompletionRequestAssistantMessageAudio": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier for a previous audio response from the model." } } }, "ChatCompletionRequestAssistantMessageContent": { "oneOf": [ { "type": "string", "description": "The text contents of the message." }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessageContentPart" }, "description": "An array of content parts with a defined type. Can be one or more of type `text`, or exactly one of type `refusal`." } ] }, "ChatCompletionRequestAssistantMessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "refusal" ] } } } ] } ] }, "ChatCompletionRequestDeveloperMessage": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/ChatCompletionRequestDeveloperMessageContent", "description": "The contents of the developer message." }, "name": { "type": [ "string", "null" ], "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } } }, "ChatCompletionRequestDeveloperMessageContent": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestDeveloperMessageContentPart" } } ] }, "ChatCompletionRequestDeveloperMessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] } ] }, "ChatCompletionRequestFunctionMessage": { "type": "object", "required": [ "name" ], "properties": { "content": { "type": [ "string", "null" ], "description": "The return value from the function call, to return to the model." }, "name": { "type": "string", "description": "The name of the function to call." } } }, "ChatCompletionRequestMessage": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestDeveloperMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "developer" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestSystemMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "system" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestUserMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "user" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestAssistantMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "assistant" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestToolMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "tool" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestFunctionMessage" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "function" ] } } } ] } ] }, "ChatCompletionRequestMessageContentPartAudio": { "type": "object", "description": "Learn about [audio inputs](https://platform.openai.com/docs/guides/audio).", "required": [ "input_audio" ], "properties": { "input_audio": { "$ref": "#/components/schemas/InputAudio" } } }, "ChatCompletionRequestMessageContentPartFile": { "type": "object", "required": [ "file" ], "properties": { "file": { "$ref": "#/components/schemas/FileObject" } } }, "ChatCompletionRequestMessageContentPartImage": { "type": "object", "required": [ "image_url" ], "properties": { "image_url": { "$ref": "#/components/schemas/ImageUrl" } } }, "ChatCompletionRequestMessageContentPartRefusal": { "type": "object", "required": [ "refusal" ], "properties": { "refusal": { "type": "string", "description": "The refusal message generated by the model." } } }, "ChatCompletionRequestMessageContentPartText": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } }, "ChatCompletionRequestSystemMessage": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/ChatCompletionRequestSystemMessageContent", "description": "The contents of the system message." }, "name": { "type": [ "string", "null" ], "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } } }, "ChatCompletionRequestSystemMessageContent": { "oneOf": [ { "type": "string", "description": "The text contents of the system message." }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestSystemMessageContentPart" }, "description": "An array of content parts with a defined type. For system messages, only type `text` is supported." } ] }, "ChatCompletionRequestSystemMessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] } ] }, "ChatCompletionRequestToolMessage": { "type": "object", "description": "Tool message", "required": [ "content", "tool_call_id" ], "properties": { "content": { "$ref": "#/components/schemas/ChatCompletionRequestToolMessageContent", "description": "The contents of the tool message." }, "tool_call_id": { "type": "string" } } }, "ChatCompletionRequestToolMessageContent": { "oneOf": [ { "type": "string", "description": "The text contents of the tool message." }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestToolMessageContentPart" }, "description": "An array of content parts with a defined type. For tool messages, only type `text` is supported." } ] }, "ChatCompletionRequestToolMessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] } ] }, "ChatCompletionRequestUserMessage": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/ChatCompletionRequestUserMessageContent", "description": "The contents of the user message." }, "name": { "type": [ "string", "null" ], "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } } }, "ChatCompletionRequestUserMessageContent": { "oneOf": [ { "type": "string", "description": "The text contents of the message." }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestUserMessageContentPart" }, "description": "An array of content parts with a defined type. Supported options differ based on the [model](https://platform.openai.com/docs/models) being used to generate the response. Can contain text, image, or audio inputs." } ] }, "ChatCompletionRequestUserMessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartImage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartAudio" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_audio" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartFile" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file" ] } } } ] } ] }, "ChatCompletionResponseMessage": { "type": "object", "description": "A chat completion message generated by the model.", "required": [ "role" ], "properties": { "content": { "type": [ "string", "null" ], "description": "The contents of the message." }, "refusal": { "type": [ "string", "null" ], "description": "The refusal message generated by the model." }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionMessageToolCalls" }, "description": "The tool calls generated by the model, such as function calls." }, "annotations": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionResponseMessageAnnotation" } }, "role": { "$ref": "#/components/schemas/Role", "description": "The role of the author of this message." }, "function_call": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionCall", "description": "Deprecated and replaced by `tool_calls`.\nThe name and arguments of a function that should be called, as generated by the model." } ] }, "audio": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionResponseMessageAudio", "description": "If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)." } ] } } }, "ChatCompletionResponseMessageAnnotation": { "oneOf": [ { "type": "object", "required": [ "url_citation", "type" ], "properties": { "url_citation": { "$ref": "#/components/schemas/UrlCitation" }, "type": { "type": "string", "enum": [ "url_citation" ] } } } ] }, "ChatCompletionResponseMessageAudio": { "type": "object", "required": [ "id", "expires_at", "data", "transcript" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this audio response." }, "expires_at": { "type": "integer", "format": "int64", "description": "The Unix timestamp (in seconds) for when this audio response will no longer be accessible on the server for use in multi-turn conversations.", "minimum": 0 }, "data": { "type": "string", "description": "Base64 encoded audio bytes generated by the model, in the format specified in the request." }, "transcript": { "type": "string", "description": "Transcript of the audio generated by the model." } } }, "ChatCompletionStreamOptions": { "type": "object", "description": "Options for streaming response. Only set this when you set `stream: true`.", "properties": { "include_usage": { "type": [ "boolean", "null" ], "description": "If set, an additional chunk will be streamed before the `data: [DONE]`\nmessage. The `usage` field on this chunk shows the token usage statistics\nfor the entire request, and the `choices` field will always be an empty\narray.\n\nAll other chunks will also include a `usage` field, but with a null\nvalue. **NOTE:** If the stream is interrupted, you may not receive the\nfinal usage chunk which contains the total token usage for the request." }, "include_obfuscation": { "type": [ "boolean", "null" ], "description": "When true, stream obfuscation will be enabled. Stream obfuscation adds\nrandom characters to an `obfuscation` field on streaming delta events to\nnormalize payload sizes as a mitigation to certain side-channel attacks.\nThese obfuscation fields are included by default, but add a small amount\nof overhead to the data stream. You can set `include_obfuscation` to\nfalse to optimize for bandwidth if you trust the network links between\nyour application and the OpenAI API." } } }, "ChatCompletionStreamResponseDelta": { "type": "object", "description": "A chat completion delta generated by streamed model responses.", "properties": { "content": { "type": [ "string", "null" ], "description": "The contents of the chunk message." }, "function_call": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionCallStream", "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model." } ] }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionMessageToolCallChunk" } }, "role": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Role", "description": "The role of the author of this message." } ] }, "refusal": { "type": [ "string", "null" ], "description": "The refusal message generated by the model." } } }, "ChatCompletionTokenLogprob": { "type": "object", "required": [ "token", "logprob", "top_logprobs" ], "properties": { "token": { "type": "string", "description": "The token." }, "logprob": { "type": "number", "format": "float", "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely." }, "bytes": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token." }, "top_logprobs": { "type": "array", "items": { "$ref": "#/components/schemas/TopLogprobs" }, "description": "List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned." } } }, "ChatCompletionTool": { "type": "object", "required": [ "function" ], "properties": { "function": { "$ref": "#/components/schemas/FunctionObject" } } }, "ChatCompletionToolChoiceOption": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionAllowedToolsChoice" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionNamedToolChoice" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionNamedToolChoiceCustom" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceOptions" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mode" ] } } } ] } ], "description": "Controls which (if any) tool is called by the model.\n`none` means the model will not call any tool and instead generates a message.\n`auto` means the model can pick between generating a message or calling one or more tools.\n`required` means the model must call one or more tools.\nSpecifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.\n\n`none` is the default when no tools are present. `auto` is the default if tools are present." }, "ChatCompletionTools": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionTool", "description": "A function tool that can be used to generate a response." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ], "description": "A function tool that can be used to generate a response." }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolChatCompletions", "description": "A custom tool that processes input using a specified format." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ], "description": "A custom tool that processes input using a specified format." } ] }, "ChatRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "stream": { "type": [ "boolean", "null" ] }, "format": { "type": [ "string", "null" ] }, "keep_alive": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Duration" } ] }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Options" } ] } } }, "ClickButtonType": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ] }, "ClickParam": { "type": "object", "description": "A click action.", "required": [ "button", "x", "y" ], "properties": { "button": { "$ref": "#/components/schemas/ClickButtonType", "description": "Indicates which mouse button was pressed during the click. One of `left`,\n`right`, `wheel`, `back`, or `forward`." }, "x": { "type": "integer", "format": "int32", "description": "The x-coordinate where the click occurred." }, "y": { "type": "integer", "format": "int32", "description": "The y-coordinate where the click occurred." } } }, "CodeInterpreterContainerAuto": { "type": "object", "description": "Auto configuration for code interpreter container.", "properties": { "file_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "An optional list of uploaded files to make available to your code." }, "memory_limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "CodeInterpreterOutputImage": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL of the image output from the code interpreter." } } }, "CodeInterpreterOutputLogs": { "type": "object", "required": [ "logs" ], "properties": { "logs": { "type": "string", "description": "The logs output from the code interpreter." } } }, "CodeInterpreterTool": { "type": "object", "required": [ "container" ], "properties": { "container": { "$ref": "#/components/schemas/CodeInterpreterToolContainer", "description": "The code interpreter container. Can be a container ID or an object that\nspecifies uploaded file IDs to make available to your code, along with an\noptional `memory_limit` setting." } } }, "CodeInterpreterToolCall": { "type": "object", "description": "Output of a code interpreter request.", "required": [ "container_id", "id", "status" ], "properties": { "code": { "type": [ "string", "null" ], "description": "The code to run, or null if not available." }, "container_id": { "type": "string", "description": "ID of the container used to run the code." }, "id": { "type": "string", "description": "The unique ID of the code interpreter tool call." }, "outputs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CodeInterpreterToolCallOutput" }, "description": "The outputs generated by the code interpreter, such as logs or images.\nCan be null if no outputs are available." }, "status": { "$ref": "#/components/schemas/CodeInterpreterToolCallStatus", "description": "The status of the code interpreter tool call.\nValid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`." } } }, "CodeInterpreterToolCallOutput": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterOutputLogs", "description": "Code interpreter output logs" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "logs" ] } } } ], "description": "Code interpreter output logs" }, { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterOutputImage", "description": "Code interpreter output image" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image" ] } } } ], "description": "Code interpreter output image" } ], "description": "Individual result from a code interpreter: either logs or files." }, "CodeInterpreterToolCallStatus": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ] }, "CodeInterpreterToolContainer": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterContainerAuto", "description": "Configuration for a code interpreter container. Optionally specify the IDs of the\nfiles to run the code on." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "auto" ] } } } ], "description": "Configuration for a code interpreter container. Optionally specify the IDs of the\nfiles to run the code on." }, { "type": "object", "description": "The container ID.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_i_d" ] } } } ], "description": "Container configuration for a code interpreter." }, "CompactionBody": { "type": "object", "description": "A compaction item generated by the `/v1/responses/compact` API.", "required": [ "id", "encrypted_content" ], "properties": { "id": { "type": "string", "description": "The unique ID of the compaction item." }, "encrypted_content": { "type": "string", "description": "The encrypted content that was produced by compaction." }, "created_by": { "type": [ "string", "null" ], "description": "The identifier of the actor that created the item." } } }, "CompactionSummaryItemParam": { "type": "object", "description": "A compaction item generated by the `/v1/responses/compact` API.", "required": [ "encrypted_content" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The ID of the compaction item." }, "encrypted_content": { "type": "string", "description": "The encrypted content of the compaction summary." } } }, "ComparisonFilter": { "type": "object", "description": "Single comparison filter.", "required": [ "type", "key", "value" ], "properties": { "type": { "$ref": "#/components/schemas/ComparisonType", "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "type": "object", "description": "The value to compare against the attribute key; supports string, number, or boolean types." } } }, "ComparisonType": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "nin" ] }, "CompletionTokensDetails": { "type": "object", "description": "Breakdown of tokens used in a completion.", "properties": { "accepted_prediction_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "audio_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Audio input tokens generated by the model.", "minimum": 0 }, "reasoning_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Tokens generated by the model for reasoning.", "minimum": 0 }, "rejected_prediction_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": " When using Predicted Outputs, the number of tokens in the\nprediction that did not appear in the completion. However, like\nreasoning tokens, these tokens are still counted in the total\ncompletion tokens for purposes of billing, output, and context\nwindow limits.", "minimum": 0 } } }, "CompletionUsage": { "type": "object", "description": "Usage statistics for the completion request.", "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "format": "int32", "description": "Number of tokens in the prompt.", "minimum": 0 }, "completion_tokens": { "type": "integer", "format": "int32", "description": "Number of tokens in the generated completion.", "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int32", "description": "Total number of tokens used in the request (prompt + completion).", "minimum": 0 }, "prompt_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptTokensDetails", "description": "Breakdown of tokens used in the prompt." } ] }, "completion_tokens_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompletionTokensDetails", "description": "Breakdown of tokens used in a completion." } ] } } }, "CompoundFilter": { "type": "object", "description": "Combine multiple filters using `and` or `or`.", "required": [ "type", "filters" ], "properties": { "type": { "$ref": "#/components/schemas/CompoundType", "description": "'Type of operation: `and` or `or`.'" }, "filters": { "type": "array", "items": { "type": "object" }, "description": "Array of filters to combine. Items can be ComparisonFilter or CompoundFilter." } } }, "CompoundType": { "type": "string", "enum": [ "and", "or" ] }, "ComputerAction": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ClickParam", "description": "A click action." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "click" ] } } } ], "description": "A click action." }, { "allOf": [ { "$ref": "#/components/schemas/DoubleClickAction", "description": "A double click action." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "double_click" ] } } } ], "description": "A double click action." }, { "allOf": [ { "$ref": "#/components/schemas/DragParam", "description": "A drag action." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "drag" ] } } } ], "description": "A drag action." }, { "allOf": [ { "$ref": "#/components/schemas/KeyPressAction", "description": "A collection of keypresses the model would like to perform." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "keypress" ] } } } ], "description": "A collection of keypresses the model would like to perform." }, { "allOf": [ { "$ref": "#/components/schemas/MoveParam", "description": "A mouse move action." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "move" ] } } } ], "description": "A mouse move action." }, { "type": "object", "description": "A screenshot action.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "screenshot" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/ScrollParam", "description": "A scroll action." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "scroll" ] } } } ], "description": "A scroll action." }, { "allOf": [ { "$ref": "#/components/schemas/TypeParam", "description": "An action to type in text." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "type" ] } } } ], "description": "An action to type in text." }, { "type": "object", "description": "A wait action.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "wait" ] } } } ], "description": "Represents all user‐triggered actions." }, "ComputerCallOutputItemParam": { "type": "object", "required": [ "call_id", "output" ], "properties": { "call_id": { "type": "string", "description": "The ID of the computer tool call that produced the output." }, "output": { "$ref": "#/components/schemas/ComputerScreenshotImage", "description": "A computer screenshot image used with the computer use tool." }, "acknowledged_safety_checks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComputerCallSafetyCheckParam" }, "description": "The safety checks reported by the API that have been acknowledged by the developer." }, "id": { "type": [ "string", "null" ], "description": "The unique ID of the computer tool call output. Optional when creating." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the message input. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when input items are returned via API." } ] } } }, "ComputerCallSafetyCheckParam": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "type": [ "string", "null" ], "description": "The type of the pending safety check." }, "message": { "type": [ "string", "null" ], "description": "Details about the pending safety check." } } }, "ComputerEnvironment": { "type": "string", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ] }, "ComputerScreenshotImage": { "type": "object", "description": "A computer screenshot image used with the computer use tool.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/ComputerScreenshotImageType", "description": "Specifies the event type. For a computer screenshot, this property is always\nset to `computer_screenshot`." }, "file_id": { "type": [ "string", "null" ], "description": "The identifier of an uploaded file that contains the screenshot." }, "image_url": { "type": [ "string", "null" ], "description": "The URL of the screenshot image." } } }, "ComputerScreenshotImageType": { "type": "string", "enum": [ "computer_screenshot" ] }, "ComputerTool": { "type": "object", "description": "A tool that controls a virtual computer. Learn more about the\n[computer tool](https://platform.openai.com/docs/guides/tools-computer-use)." }, "ComputerToolCall": { "type": "object", "description": "Output from a computer tool call.", "required": [ "call_id", "id", "pending_safety_checks", "status" ], "properties": { "action": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ComputerAction" } ] }, "actions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComputerAction" }, "description": "Flattened batched actions for `computer_use`. Each action includes a\n`type` discriminator and action-specific fields." }, "call_id": { "type": "string", "description": "An identifier used when responding to the tool call with output." }, "id": { "type": "string", "description": "The unique ID of the computer call." }, "pending_safety_checks": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerCallSafetyCheckParam" }, "description": "The pending safety checks for the computer call." }, "status": { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when items are returned via API." } } }, "ComputerUsePreviewTool": { "type": "object", "required": [ "environment", "display_width", "display_height" ], "properties": { "environment": { "$ref": "#/components/schemas/ComputerEnvironment", "description": "The type of computer environment to control." }, "display_width": { "type": "integer", "format": "int32", "description": "The width of the computer display.", "minimum": 0 }, "display_height": { "type": "integer", "format": "int32", "description": "The height of the computer display.", "minimum": 0 } } }, "ContainerAutoParam": { "type": "object", "description": "Automatically creates a container for the request.", "properties": { "file_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "An optional list of uploaded file IDs to make available in the container." }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContainerNetworkPolicy", "description": "Network access policy for the container." } ] }, "skills": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SkillParam" }, "description": "An optional list of skills to make available in the container." } } }, "ContainerFileCitationBody": { "type": "object", "required": [ "container_id", "end_index", "file_id", "filename", "start_index" ], "properties": { "container_id": { "type": "string", "description": "The ID of the container file." }, "end_index": { "type": "integer", "format": "int32", "description": "The index of the last character of the container file citation in the message.", "minimum": 0 }, "file_id": { "type": "string", "description": "The ID of the file." }, "filename": { "type": "string", "description": "The filename of the container file cited." }, "start_index": { "type": "integer", "format": "int32", "description": "The index of the first character of the container file citation in the message.", "minimum": 0 } } }, "ContainerNetworkPolicy": { "oneOf": [ { "type": "object", "description": "Disable all outbound network access.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "disabled" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/ContainerNetworkPolicyAllowlistDetails", "description": "Allow access only to specified domains." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "allowlist" ] } } } ], "description": "Allow access only to specified domains." } ], "description": "Network access policy for a container." }, "ContainerNetworkPolicyAllowlistDetails": { "type": "object", "description": "Details for an allowlist network policy.", "required": [ "allowed_domains" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "A list of allowed domains." }, "domain_secrets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ContainerNetworkPolicyDomainSecretParam" }, "description": "Optional domain-scoped secrets for allowlisted domains." } } }, "ContainerNetworkPolicyDomainSecretParam": { "type": "object", "description": "A domain-scoped secret injected for allowlisted domains.", "required": [ "domain", "name", "value" ], "properties": { "domain": { "type": "string", "description": "The domain associated with the secret." }, "name": { "type": "string", "description": "The name of the secret to inject for the domain." }, "value": { "type": "string", "description": "The secret value to inject for the domain." } } }, "ContainerReferenceParam": { "type": "object", "description": "References a container created with the /v1/containers endpoint.", "required": [ "container_id" ], "properties": { "container_id": { "type": "string", "description": "The ID of the referenced container." } } }, "ContainerReferenceResource": { "type": "object", "description": "A resource reference to a container by ID.", "required": [ "container_id" ], "properties": { "container_id": { "type": "string", "description": "The ID of the referenced container." } } }, "ContextLimits": { "type": "object", "properties": { "max_input_tokens": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "Conversation": { "type": "object", "description": "The conversation that this response belonged to. Input items and output items from this\nresponse were automatically added to this conversation.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique ID of the conversation that this response was associated with." } } }, "ConversationParam": { "oneOf": [ { "type": "string", "description": "The unique ID of the conversation." }, { "$ref": "#/components/schemas/Conversation", "description": "The conversation that this response belongs to." } ] }, "CoordParam": { "type": "object", "description": "An x/y coordinate pair.", "required": [ "x", "y" ], "properties": { "x": { "type": "integer", "format": "int32", "description": "The x-coordinate." }, "y": { "type": "integer", "format": "int32", "description": "The y-coordinate." } } }, "CopyAliasRequest": { "type": "object", "required": [ "alias" ], "properties": { "alias": { "type": "string" } } }, "CreateAccessRequest": { "type": "object", "description": "Request for creating an app access request", "required": [ "app_client_id", "flow_type", "requested_role", "requested" ], "properties": { "app_client_id": { "type": "string", "description": "App client ID from Keycloak" }, "flow_type": { "$ref": "#/components/schemas/FlowType", "description": "Flow type: \"redirect\" or \"popup\"" }, "redirect_url": { "type": [ "string", "null" ], "description": "Redirect URL for result notification (required for redirect flow)" }, "requested_role": { "$ref": "#/components/schemas/UserScope", "description": "Role requested for the external app (scope_user_user or scope_user_power_user)" }, "requested": { "$ref": "#/components/schemas/RequestedResources", "description": "Resources requested (tools, etc.)" } }, "example": { "app_client_id": "my-app-client", "flow_type": "redirect", "redirect_url": "https://myapp.com/callback", "requested": { "mcp_servers": [ { "url": "https://mcp.example.com/mcp" } ], "version": "1" }, "requested_role": "scope_user_user" } }, "CreateAccessRequestResponse": { "type": "object", "required": [ "id", "status", "review_url" ], "properties": { "id": { "type": "string", "description": "Access request ID" }, "status": { "$ref": "#/components/schemas/AppAccessRequestStatus", "description": "Status (always \"draft\")" }, "review_url": { "type": "string", "description": "Review URL for user to approve/deny" } }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "review_url": "http://localhost:1135/ui/apps/access-requests/review?id=550e8400-e29b-41d4-a716-446655440000", "status": "draft" } }, "CreateAuthConfig": { "allOf": [ { "$ref": "#/components/schemas/CreateMcpAuthConfigRequest" }, { "type": "object", "required": [ "mcp_server_id" ], "properties": { "mcp_server_id": { "type": "string" } } } ], "description": "Wrapper for creating auth configs with server_id in body instead of path" }, "CreateChatCompletionRequest": { "type": "object", "required": [ "messages", "model" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestMessage" }, "description": "A list of messages comprising the conversation so far. Depending on the\n[model](https://platform.openai.com/docs/models) you use, different message types (modalities)\nare supported, like [text](https://platform.openai.com/docs/guides/text-generation),\n[images](https://platform.openai.com/docs/guides/vision), and\n[audio](https://platform.openai.com/docs/guides/audio)." }, "model": { "type": "string", "description": "Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the\n[model guide](https://platform.openai.com/docs/models)\nto browse and compare available models." }, "modalities": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ResponseModalities" }, "description": "Output types that you would like the model to generate. Most models are capable of generating\ntext, which is the default:\n\n`[\"text\"]`\nThe `gpt-4o-audio-preview` model can also be used to\n[generate audio](https://platform.openai.com/docs/guides/audio). To request that this model\ngenerate both text and audio responses, you can use:\n\n`[\"text\", \"audio\"]`" }, "verbosity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Verbosity", "description": "Constrains the verbosity of the model's response. Lower values will result in\nmore concise responses, while higher values will result in more verbose responses.\nCurrently supported values are `low`, `medium`, and `high`." } ] }, "reasoning_effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffort", "description": "Constrains effort on reasoning for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently supported values are `minimal`, `low`, `medium`, and `high`. Reducing\nreasoning effort can result in faster responses and fewer tokens used\non reasoning in a response.\nNote: The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort." } ] }, "max_completion_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "An upper bound for the number of tokens that can be generated for a completion, including\nvisible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).", "minimum": 0 }, "frequency_penalty": { "type": [ "number", "null" ], "format": "float", "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on\ntheir existing frequency in the text so far, decreasing the model's\nlikelihood to repeat the same line verbatim." }, "presence_penalty": { "type": [ "number", "null" ], "format": "float", "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on\nwhether they appear in the text so far, increasing the model's likelihood\nto talk about new topics." }, "web_search_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchOptions", "description": "This tool searches the web for relevant results to use in a response.\nLearn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat)." } ] }, "top_logprobs": { "type": [ "integer", "null" ], "format": "int32", "description": "An integer between 0 and 20 specifying the number of most likely tokens to\nreturn at each token position, each with an associated log probability.\n`logprobs` must be set to `true` if this parameter is used.", "minimum": 0 }, "response_format": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseFormat", "description": "An object specifying the format that the model must output.\n\nSetting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables\nStructured Outputs which ensures the model will match your supplied JSON\nschema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).\n\nSetting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which\nensures the message the model generates is valid JSON. Using `json_schema`\nis preferred for models that support it." } ] }, "audio": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionAudio", "description": "Parameters for audio output. Required when audio output is requested with\n`modalities: [\"audio\"]`. [Learn more](https://platform.openai.com/docs/guides/audio)." } ] }, "store": { "type": [ "boolean", "null" ], "description": "Whether or not to store the output of this chat completion request for\nuse in our [model distillation](https://platform.openai.com/docs/guides/distillation) or\n[evals](https://platform.openai.com/docs/guides/evals) products.\n\nSupports text and image inputs. Note: image inputs over 8MB will be dropped." }, "stream": { "type": [ "boolean", "null" ], "description": "If set to true, the model response data will be streamed to the client\nas it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).\nSee the [Streaming section below](https://platform.openai.com/docs/api-reference/chat/streaming)\nfor more information, along with the [streaming responses](https://platform.openai.com/docs/guides/streaming-responses)\nguide for more information on how to handle the streaming events." }, "stop": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StopConfiguration", "description": "Not supported with latest reasoning models `o3` and `o4-mini`.\n\nUp to 4 sequences where the API will stop generating further tokens. The\nreturned text will not contain the stop sequence." } ] }, "logit_bias": { "type": [ "object", "null" ], "description": "Modify the likelihood of specified tokens appearing in the completion.\n\nAccepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100.\nMathematically, the bias is added to the logits generated by the model prior to sampling.\nThe exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection;\nvalues like -100 or 100 should result in a ban or exclusive selection of the relevant token.", "additionalProperties": { "type": "integer", "format": "int32" }, "propertyNames": { "type": "string" } }, "logprobs": { "type": [ "boolean", "null" ], "description": "Whether to return log probabilities of the output tokens or not. If true,\nreturns the log probabilities of each output token returned in the `content` of `message`." }, "max_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "The maximum number of [tokens](https://platform.openai.com/tokenizer) that can be generated in\nthe chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API.\nThis value is now deprecated in favor of `max_completion_tokens`, and is\nnot compatible with [o-series models](https://platform.openai.com/docs/guides/reasoning).", "deprecated": true, "minimum": 0 }, "n": { "type": [ "integer", "null" ], "format": "int32", "description": "How many chat completion choices to generate for each input message. Note that you will be\ncharged based on the number of generated tokens across all of the choices. Keep `n` as `1` to\nminimize costs.", "minimum": 0 }, "prediction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PredictionContent", "description": "Configuration for a [Predicted Output](https://platform.openai.com/docs/guides/predicted-outputs),\nwhich can greatly improve response times when large parts of the model\nresponse are known ahead of time. This is most common when you are\nregenerating a file with only minor changes to most of the content." } ] }, "seed": { "type": [ "integer", "null" ], "format": "int64", "description": "This feature is in Beta.\n\nIf specified, our system will make a best effort to sample deterministically, such that\nrepeated requests with the same `seed` and parameters should return the same result.\n\nDeterminism is not guaranteed, and you should refer to the `system_fingerprint` response\nparameter to monitor changes in the backend.", "deprecated": true }, "stream_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionStreamOptions" } ] }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Specifies the processing type used for serving the request.\n- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.\n- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.\n- If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.\n- When not set, the default behavior is 'auto'.\n\nWhen the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter." } ] }, "temperature": { "type": [ "number", "null" ], "format": "float", "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random,\nwhile lower values like 0.2 will make it more focused and deterministic.\n\nWe generally recommend altering this or `top_p` but not both." }, "top_p": { "type": [ "number", "null" ], "format": "float", "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability mass.\nSo 0.1 means only the tokens comprising the top 10% probability mass are considered.\n\n We generally recommend altering this or `temperature` but not both." }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionTools" }, "description": "A list of tools the model may call. You can provide either\n[custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) or\n[function tools](https://platform.openai.com/docs/guides/function-calling)." }, "tool_choice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionToolChoiceOption", "description": "Controls which (if any) tool is called by the model.\n`none` means the model will not call any tool and instead generates a message.\n`auto` means the model can pick between generating a message or calling one or more tools.\n`required` means the model must call one or more tools.\nSpecifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces\nthe model to call that tool.\n`none` is the default when no tools are present. `auto` is the default if tools are present." } ] }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling)\nduring tool use." }, "user": { "type": [ "string", "null" ], "description": "This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key`\ninstead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and\nprevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).", "deprecated": true }, "safety_identifier": { "type": [ "string", "null" ], "description": "A stable identifier used to help detect users of your application that may be violating OpenAI's\nusage policies.\n\nThe IDs should be a string that uniquely identifies each user. We recommend hashing their username\nor email address, in order to avoid sending us any identifying information. [Learn\nmore](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers)." }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces\nthe `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching)." }, "function_call": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatCompletionFunctionCall", "description": "Deprecated in favor of `tool_choice`.\n\nControls which (if any) function is called by the model.\n`none` means the model will not call a function and instead generates a message.\n`auto` means the model can pick between generating a message or calling a function.\nSpecifying a particular function via `{\"name\": \"my_function\"}` forces the model to call that function.\n\n`none` is the default when no functions are present. `auto` is the default if functions are present." } ] }, "functions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChatCompletionFunctions" }, "description": "Deprecated in favor of `tools`.\n\nA list of functions the model may generate JSON inputs for.", "deprecated": true }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Metadata", "description": "Developer-defined tags and values used for filtering completions in the [dashboard](https://platform.openai.com/chat-completions)." } ] } } }, "CreateChatCompletionResponse": { "type": "object", "description": "Represents a chat completion response returned by model, based on the provided input.", "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoice" }, "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1." }, "created": { "type": "integer", "format": "int32", "description": "The Unix timestamp (in seconds) of when the chat completion was created.", "minimum": 0 }, "model": { "type": "string", "description": "The model used for the chat completion." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "The service tier used for processing the request. This field is only included if the `service_tier` parameter is specified in the request." } ] }, "system_fingerprint": { "type": [ "string", "null" ], "description": "This fingerprint represents the backend configuration that the model runs with.\n\nCan be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.", "deprecated": true }, "object": { "type": "string", "description": "The object type, which is always `chat.completion`." }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompletionUsage" } ] } } }, "CreateChatCompletionStreamResponse": { "type": "object", "description": "Represents a streamed chunk of a chat completion response returned by the model, based on the provided input. [Learn more](https://platform.openai.com/docs/guides/streaming-responses).", "required": [ "id", "choices", "created", "model", "object" ], "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion. Each chunk has the same ID." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatChoiceStream" }, "description": "A list of chat completion choices. Can contain more than one elements if `n` is greater than 1. Can also be empty for the last chunk if you set `stream_options: {\"include_usage\": true}`." }, "created": { "type": "integer", "format": "int32", "description": "The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.", "minimum": 0 }, "model": { "type": "string", "description": "The model to generate the completion." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "The service tier used for processing the request. This field is only included if the `service_tier` parameter is specified in the request." } ] }, "system_fingerprint": { "type": [ "string", "null" ], "description": "This fingerprint represents the backend configuration that the model runs with.\nCan be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.", "deprecated": true }, "object": { "type": "string", "description": "The object type, which is always `chat.completion.chunk`." }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompletionUsage", "description": "An optional field that will only be present when you set `stream_options: {\"include_usage\": true}` in your request.\nWhen present, it contains a null value except for the last chunk which contains the token usage statistics for the entire request." } ] } } }, "CreateEmbeddingRequest": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string", "description": "ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list)\nAPI to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models)\nfor descriptions of them." }, "input": { "$ref": "#/components/schemas/EmbeddingInput", "description": "Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single\nrequest, pass an array of strings or array of token arrays. The input must not exceed the max\ninput tokens for the model (8192 tokens for all embedding models), cannot be an empty string, and\nany array must be 2048 dimensions or less. [Example Python\ncode](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.\nIn addition to the per-input token limit, all embedding models enforce a maximum of 300,000\ntokens summed across all inputs in a single request." }, "encoding_format": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EncodingFormat", "description": "The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/)." } ] }, "user": { "type": [ "string", "null" ], "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.\n[Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids)." }, "dimensions": { "type": [ "integer", "null" ], "format": "int32", "description": "The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models.", "minimum": 0 } } }, "CreateEmbeddingResponse": { "type": "object", "required": [ "object", "model", "data", "usage" ], "properties": { "object": { "type": "string" }, "model": { "type": "string", "description": "The name of the model used to generate the embedding." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Embedding" }, "description": "The list of embeddings generated by the model." }, "usage": { "$ref": "#/components/schemas/EmbeddingUsage", "description": "The usage information for the request." } } }, "CreateMcpAuthConfigRequest": { "oneOf": [ { "type": "object", "required": [ "name", "entries", "type" ], "properties": { "name": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/McpAuthConfigParamInput" } }, "type": { "type": "string", "enum": [ "header" ] } } }, { "type": "object", "required": [ "name", "client_id", "authorization_endpoint", "token_endpoint", "type" ], "properties": { "name": { "type": "string" }, "client_id": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "client_secret": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] }, "registration_type": { "$ref": "#/components/schemas/RegistrationType", "description": "`\"pre_registered\"` (default) or `\"dynamic_registration\"`" }, "registration_access_token": { "type": [ "string", "null" ] }, "registration_endpoint": { "type": [ "string", "null" ] }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "client_id_issued_at": { "type": [ "integer", "null" ], "format": "int64" }, "type": { "type": "string", "enum": [ "oauth" ] } } } ], "description": "Discriminated union for creating any type of MCP auth config.\nThe JSON `\"type\"` field determines the variant: `\"header\"` or `\"oauth\"`." }, "CreateResponse": { "type": "object", "description": "Builder for a Responses API request.", "required": [ "input" ], "properties": { "background": { "type": [ "boolean", "null" ], "description": "Whether to run the model response in the background.\n[Learn more](https://platform.openai.com/docs/guides/background)." }, "conversation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConversationParam", "description": "The conversation that this response belongs to. Items from this conversation are prepended to\n `input_items` for this response request.\n\nInput items and output items from this response are automatically added to this conversation after\nthis response completes." } ] }, "include": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/IncludeEnum" }, "description": "Specify additional output data to include in the model response. Currently supported\nvalues are:\n\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution in code\n interpreter tool call items.\n\n- `computer_call_output.output.image_url`: Include image urls from the computer call\n output.\n\n- `file_search_call.results`: Include the search results of the file search tool call.\n\n- `message.input_image.image_url`: Include image urls from the input message.\n\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in\n reasoning item outputs. This enables reasoning items to be used in multi-turn\n conversations when using the Responses API statelessly (like when the `store` parameter is\n set to `false`, or when an organization is enrolled in the zero data retention program)." }, "input": { "$ref": "#/components/schemas/InputParam", "description": "Text, image, or file inputs to the model, used to generate a response.\n\nLearn more:\n- [Text inputs and outputs](https://platform.openai.com/docs/guides/text)\n- [Image inputs](https://platform.openai.com/docs/guides/images)\n- [File inputs](https://platform.openai.com/docs/guides/pdf-files)\n- [Conversation state](https://platform.openai.com/docs/guides/conversation-state)\n- [Function calling](https://platform.openai.com/docs/guides/function-calling)" }, "instructions": { "type": [ "string", "null" ], "description": "A system (or developer) message inserted into the model's context.\n\nWhen using along with `previous_response_id`, the instructions from a previous\nresponse will not be carried over to the next response. This makes it simple\nto swap out system (or developer) messages in new responses." }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "An upper bound for the number of tokens that can be generated for a response, including\nvisible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).", "minimum": 0 }, "max_tool_calls": { "type": [ "integer", "null" ], "format": "int32", "description": "The maximum number of total calls to built-in tools that can be processed in a response. This\nmaximum number applies across all built-in tool calls, not per individual tool. Any further\nattempts to call a tool by the model will be ignored.", "minimum": 0 }, "metadata": { "type": [ "object", "null" ], "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard.\n\nKeys are strings with a maximum length of 64 characters. Values are\nstrings with a maximum length of 512 characters.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "model": { "type": [ "string", "null" ], "description": "Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)\nto browse and compare available models." }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Whether to allow the model to run tool calls in parallel." }, "previous_response_id": { "type": [ "string", "null" ], "description": "The unique ID of the previous response to the model. Use this to create multi-turn conversations.\nLearn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state).\nCannot be used in conjunction with `conversation`." }, "prompt": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Prompt", "description": "Reference to a prompt template and its variables.\n[Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts)." } ] }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces\nthe `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching)." }, "prompt_cache_retention": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptCacheRetention", "description": "The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching,\nwhich keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn\nmore](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention)." } ] }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Reasoning", "description": "**gpt-5 and o-series models only**\nConfiguration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning)." } ] }, "safety_identifier": { "type": [ "string", "null" ], "description": "A stable identifier used to help detect users of your application that may be violating OpenAI's\nusage policies.\n\nThe IDs should be a string that uniquely identifies each user. We recommend hashing their username\nor email address, in order to avoid sending us any identifying information. [Learn\nmore](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers)." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Specifies the processing type used for serving the request.\n- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.\n- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.\n- If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.\n- When not set, the default behavior is 'auto'.\n\nWhen the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter." } ] }, "store": { "type": [ "boolean", "null" ], "description": "Whether to store the generated model response for later retrieval via API." }, "stream": { "type": [ "boolean", "null" ], "description": "If set to true, the model response data will be streamed to the client\nas it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).\nSee the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming)\nfor more information." }, "stream_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseStreamOptions", "description": "Options for streaming responses. Only set this when you set `stream: true`." } ] }, "temperature": { "type": [ "number", "null" ], "format": "float", "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8\nwill make the output more random, while lower values like 0.2 will make it\nmore focused and deterministic. We generally recommend altering this or\n`top_p` but not both." }, "text": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseTextParam", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](https://platform.openai.com/docs/guides/text)\n- [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)" } ] }, "tool_choice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolChoiceParam", "description": "How the model should select which tool (or tools) to use when generating\na response. See the `tools` parameter to see how to specify which tools\nthe model can call." } ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Tool" }, "description": "An array of tools the model may call while generating a response. You\ncan specify which tool to use by setting the `tool_choice` parameter.\n\nWe support the following categories of tools:\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search)\n or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about\n [built-in tools](https://platform.openai.com/docs/guides/tools).\n- **MCP Tools**: Integrations with third-party systems via custom MCP servers\n or predefined connectors such as Google Drive and SharePoint. Learn more about\n [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp).\n- **Function calls (custom tools)**: Functions that are defined by you,\n enabling the model to call your own code with strongly typed arguments\n and outputs. Learn more about\n [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use\n custom tools to call your own code." }, "top_logprobs": { "type": [ "integer", "null" ], "format": "int32", "description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each\ntoken position, each with an associated log probability.", "minimum": 0 }, "top_p": { "type": [ "number", "null" ], "format": "float", "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability\nmass. So 0.1 means only the tokens comprising the top 10% probability mass\nare considered.\n\nWe generally recommend altering this or `temperature` but not both." }, "truncation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Truncation", "description": "The truncation strategy to use for the model response.\n - `auto`: If the input to this Response exceeds\n the model's context window size, the model will truncate the\n response to fit the context window by dropping items from the beginning of the conversation.\n - `disabled` (default): If the input size will exceed the context window\n size for a model, the request will fail with a 400 error." } ] } } }, "CreateTenantRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } } }, "CreateTenantResponse": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" } } }, "CreateTokenRequest": { "type": "object", "required": [ "scope" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Descriptive name for the API token", "example": "My Integration Token", "maxLength": 100, "minLength": 0 }, "scope": { "$ref": "#/components/schemas/TokenScope", "description": "Token scope defining access level" } }, "example": { "name": "My Integration Token", "scope": "scope_token_user" } }, "CustomGrammarFormatParam": { "type": "object", "required": [ "definition", "syntax" ], "properties": { "definition": { "type": "string", "description": "The grammar definition." }, "syntax": { "$ref": "#/components/schemas/GrammarSyntax", "description": "The syntax of the grammar definition. One of `lark` or `regex`." } } }, "CustomName": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the custom tool to call." } } }, "CustomTool": { "type": "object", "required": [ "name", "input" ], "properties": { "name": { "type": "string", "description": "The name of the custom tool to call." }, "input": { "type": "string", "description": "The input for the custom tool call generated by the model." } } }, "CustomToolCall": { "type": "object", "required": [ "call_id", "input", "name", "id" ], "properties": { "call_id": { "type": "string", "description": "An identifier used to map this custom tool call to a tool call output." }, "namespace": { "type": [ "string", "null" ], "description": "The namespace of the custom tool being called." }, "input": { "type": "string", "description": "The input for the custom tool call generated by the model." }, "name": { "type": "string", "description": "The name of the custom tool being called." }, "id": { "type": "string", "description": "The unique ID of the custom tool call in the OpenAI platform." } } }, "CustomToolCallOutput": { "type": "object", "required": [ "call_id", "output" ], "properties": { "call_id": { "type": "string", "description": "The call ID, used to map this custom tool call output to a custom tool call." }, "output": { "$ref": "#/components/schemas/CustomToolCallOutputOutput", "description": "The output from the custom tool call generated by your code.\nCan be a string or an list of output content." }, "id": { "type": [ "string", "null" ], "description": "The unique ID of the custom tool call output in the OpenAI platform." } } }, "CustomToolCallOutputOutput": { "oneOf": [ { "type": "string", "description": "A string of the output of the custom tool call." }, { "type": "array", "items": { "$ref": "#/components/schemas/InputContent" }, "description": "Text, image, or file output of the custom tool call." } ] }, "CustomToolChatCompletions": { "type": "object", "required": [ "custom" ], "properties": { "custom": { "$ref": "#/components/schemas/CustomToolProperties" } } }, "CustomToolParam": { "type": "object", "required": [ "name", "format" ], "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls." }, "description": { "type": [ "string", "null" ], "description": "Optional description of the custom tool, used to provide more context." }, "format": { "$ref": "#/components/schemas/CustomToolParamFormat", "description": "The input format for the custom tool. Default is unconstrained text." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether this tool should be deferred and discovered via tool search." } } }, "CustomToolParamFormat": { "oneOf": [ { "type": "object", "description": "Unconstrained free-form text.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/CustomGrammarFormatParam", "description": "A grammar defined by the user." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "grammar" ] } } } ], "description": "A grammar defined by the user." } ] }, "CustomToolProperties": { "type": "object", "required": [ "name", "format" ], "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls." }, "description": { "type": [ "string", "null" ], "description": "Optional description of the custom tool, used to provide more context." }, "format": { "$ref": "#/components/schemas/CustomToolPropertiesFormat", "description": "The input format for the custom tool. Default is unconstrained text." } } }, "CustomToolPropertiesFormat": { "oneOf": [ { "type": "object", "description": "Unconstrained free-form text.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "description": "A grammar defined by the user.", "required": [ "grammar", "type" ], "properties": { "grammar": { "$ref": "#/components/schemas/CustomGrammarFormatParam" }, "type": { "type": "string", "enum": [ "grammar" ] } } } ] }, "DashboardUser": { "type": "object", "description": "Dashboard user information from a validated dashboard session token", "required": [ "user_id", "username" ], "properties": { "user_id": { "type": "string" }, "username": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] } } }, "DeleteResponse": { "type": "object", "required": [ "object", "deleted", "id" ], "properties": { "object": { "type": "string" }, "deleted": { "type": "boolean" }, "id": { "type": "string" } } }, "DeploymentMode": { "type": "string", "enum": [ "standalone", "multi_tenant" ] }, "DoubleClickAction": { "type": "object", "description": "A double click action.", "required": [ "x", "y" ], "properties": { "x": { "type": "integer", "format": "int32", "description": "The x-coordinate where the double click occurred." }, "y": { "type": "integer", "format": "int32", "description": "The y-coordinate where the double click occurred." } } }, "DownloadRequest": { "type": "object", "required": [ "id", "repo", "filename", "status", "downloaded_bytes", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "repo": { "type": "string" }, "filename": { "type": "string" }, "status": { "$ref": "#/components/schemas/DownloadStatus" }, "error": { "type": [ "string", "null" ] }, "total_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "downloaded_bytes": { "type": "integer", "format": "int64" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DownloadStatus": { "type": "string", "enum": [ "pending", "completed", "error" ] }, "DragParam": { "type": "object", "description": "A drag action.", "required": [ "path" ], "properties": { "path": { "type": "array", "items": { "$ref": "#/components/schemas/CoordParam" }, "description": "An array of coordinates representing the path of the drag action." } } }, "Duration": { "type": "string" }, "DynamicRegisterRequest": { "type": "object", "required": [ "registration_endpoint", "redirect_uri" ], "properties": { "registration_endpoint": { "type": "string" }, "redirect_uri": { "type": "string" }, "scopes": { "type": [ "string", "null" ] } } }, "DynamicRegisterResponse": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" }, "client_secret": { "type": [ "string", "null" ] }, "client_id_issued_at": { "type": [ "integer", "null" ], "format": "int64" }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "registration_access_token": { "type": [ "string", "null" ] } } }, "EasyInputContent": { "oneOf": [ { "type": "string", "description": "A text input to the model." }, { "type": "array", "items": { "$ref": "#/components/schemas/InputContent" }, "description": "A list of one or many input items to the model, containing different content types." } ], "description": "Content for EasyInputMessage - can be a simple string or structured list." }, "EasyInputMessage": { "type": "object", "description": "A simplified message input to the model (EasyInputMessage in the OpenAPI spec).\n\nThis is the most user-friendly way to provide messages, supporting both simple\nstring content and structured content. Role can include `assistant` for providing\nprevious assistant responses.", "required": [ "role", "content" ], "properties": { "type": { "$ref": "#/components/schemas/MessageType", "description": "The type of the message input. Defaults to `message` when omitted in JSON input." }, "role": { "$ref": "#/components/schemas/Role", "description": "The role of the message input. One of `user`, `assistant`, `system`, or `developer`." }, "content": { "$ref": "#/components/schemas/EasyInputContent", "description": "Text, image, or audio input to the model, used to generate a response.\nCan also contain previous assistant responses." }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessagePhase", "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or\nthe final answer (`final_answer`). Not used for user messages." } ] } } }, "Embedding": { "type": "object", "description": "Represents an embedding vector returned by embedding endpoint.", "required": [ "index", "object", "embedding" ], "properties": { "index": { "type": "integer", "format": "int32", "description": "The index of the embedding in the list of embeddings.", "minimum": 0 }, "object": { "type": "string", "description": "The object type, which is always \"embedding\"." }, "embedding": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "The embedding vector, which is a list of floats. The length of vector\ndepends on the model as listed in the [embedding guide](https://platform.openai.com/docs/guides/embeddings)." } } }, "EmbeddingInput": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, { "type": "array", "items": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } ] }, "EmbeddingUsage": { "type": "object", "required": [ "prompt_tokens", "total_tokens" ], "properties": { "prompt_tokens": { "type": "integer", "format": "int32", "description": "The number of tokens used by the prompt.", "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int32", "description": "The total number of tokens used by the request.", "minimum": 0 } } }, "EncodingFormat": { "type": "string", "enum": [ "float", "base64" ] }, "ErrorBody": { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string", "description": "Human-readable error message describing what went wrong", "example": "Validation failed: name is required" }, "type": { "type": "string", "description": "Error type categorizing the kind of error that occurred", "example": "invalid_request_error" }, "code": { "type": [ "string", "null" ], "description": "Specific error code for programmatic error handling", "example": "validation_error" }, "param": { "type": [ "object", "null" ], "description": "Additional error parameters as key-value pairs (for validation errors)", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": { "field": "name", "value": "invalid" } } }, "example": { "code": "validation_error", "message": "Validation failed: name is required", "param": { "field": "name", "value": "invalid" }, "type": "invalid_request_error" } }, "ErrorObject": { "type": "object", "description": "An error that occurred while generating the response.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A machine-readable error code that was returned." }, "message": { "type": "string", "description": "A human-readable description of the error that was returned." } } }, "FetchModelsRequest": { "type": "object", "description": "Request to fetch available models from provider", "required": [ "base_url" ], "properties": { "creds": { "$ref": "#/components/schemas/TestCreds", "description": "Credentials to use for fetching models" }, "base_url": { "type": "string", "description": "API base URL (required - always needed to know where to fetch models from)" } }, "example": { "base_url": "http://localhost:8080/v1", "creds": { "type": "api_key", "value": null } } }, "FetchModelsResponse": { "type": "object", "description": "Response containing available models from provider", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "type": "string" } } }, "example": { "models": [ "gpt-4", "gpt-3.5-turbo", "gpt-4-turbo" ] } }, "FileCitationBody": { "type": "object", "required": [ "file_id", "filename", "index" ], "properties": { "file_id": { "type": "string", "description": "The ID of the file." }, "filename": { "type": "string", "description": "The filename of the file cited." }, "index": { "type": "integer", "format": "int32", "description": "The index of the file in the list of files.", "minimum": 0 } } }, "FileObject": { "type": "object", "properties": { "file_data": { "type": [ "string", "null" ], "description": "The base64 encoded file data, used when passing the file to the model\nas a string." }, "file_id": { "type": [ "string", "null" ], "description": "The ID of an uploaded file to use as input." }, "filename": { "type": [ "string", "null" ], "description": "The name of the file, used when passing the file to the model as a\nstring." } } }, "FilePath": { "type": "object", "required": [ "file_id", "index" ], "properties": { "file_id": { "type": "string", "description": "The ID of the file." }, "index": { "type": "integer", "format": "int32", "description": "The index of the file in the list of files.", "minimum": 0 } } }, "FileSearchTool": { "type": "object", "required": [ "vector_store_ids" ], "properties": { "vector_store_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the vector stores to search." }, "max_num_results": { "type": [ "integer", "null" ], "format": "int32", "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive.", "minimum": 0 }, "filters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Filter", "description": "A filter to apply." } ] }, "ranking_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RankingOptions", "description": "Ranking options for search." } ] } } }, "FileSearchToolCall": { "type": "object", "description": "File search tool call output.", "required": [ "id", "queries", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the file search tool call." }, "queries": { "type": "array", "items": { "type": "string" }, "description": "The queries used to search for files." }, "status": { "$ref": "#/components/schemas/FileSearchToolCallStatus", "description": "The status of the file search tool call. One of `in_progress`, `searching`,\n`incomplete`,`failed`, or `completed`." }, "results": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/FileSearchToolCallResult" }, "description": "The results of the file search tool call." } } }, "FileSearchToolCallResult": { "type": "object", "description": "A single result from a file search.", "required": [ "attributes", "file_id", "filename", "score", "text" ], "properties": { "attributes": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing\nadditional information about the object in a structured format, and querying for objects\nAPI or the dashboard. Keys are strings with a maximum length of 64 characters\n. Values are strings with a maximum length of 512 characters, booleans, or numbers." }, "file_id": { "type": "string", "description": "The unique ID of the file." }, "filename": { "type": "string", "description": "The name of the file." }, "score": { "type": "number", "format": "float", "description": "The relevance score of the file - a value between 0 and 1." }, "text": { "type": "string", "description": "The text that was retrieved from the file." } } }, "FileSearchToolCallStatus": { "type": "string", "enum": [ "in_progress", "searching", "incomplete", "failed", "completed" ] }, "Filter": { "oneOf": [ { "$ref": "#/components/schemas/ComparisonFilter", "description": "A filter used to compare a specified attribute key to a given value using a defined\ncomparison operation." }, { "$ref": "#/components/schemas/CompoundFilter", "description": "Combine multiple filters using `and` or `or`." } ], "description": "Filters for file search." }, "FinishReason": { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, "FlowType": { "type": "string", "enum": [ "redirect", "popup" ] }, "FunctionCall": { "type": "object", "description": "The name and arguments of a function that should be called, as generated by the model.", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." } } }, "FunctionCallOutput": { "oneOf": [ { "type": "string", "description": "A JSON string of the output of the function tool call." }, { "type": "array", "items": { "$ref": "#/components/schemas/InputContent" } } ] }, "FunctionCallOutputItemParam": { "type": "object", "description": "Output from a function call that you're providing back to the model.", "required": [ "call_id", "output" ], "properties": { "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model." }, "output": { "$ref": "#/components/schemas/FunctionCallOutput", "description": "Text, image, or file output of the function tool call." }, "id": { "type": [ "string", "null" ], "description": "The unique ID of the function tool call output.\nPopulated when this item is returned via API." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when items are returned via API." } ] } } }, "FunctionCallOutputStatusEnum": { "type": "string", "description": "The status of a function call output.", "enum": [ "in_progress", "completed", "incomplete" ] }, "FunctionCallStatus": { "type": "string", "description": "The status of a function call.", "enum": [ "in_progress", "completed", "incomplete" ] }, "FunctionCallStream": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the function to call." }, "arguments": { "type": [ "string", "null" ], "description": "The arguments to call the function with, as generated by the model in JSON format.\nNote that the model does not always generate valid JSON, and may hallucinate\nparameters not defined by your function schema. Validate the arguments in your\ncode before calling your function." } } }, "FunctionName": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." } } }, "FunctionObject": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "description": { "type": [ "string", "null" ], "description": "A description of what the function does, used by the model to choose when and how to call the function." }, "parameters": { "type": [ "object", "null" ], "description": "The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/text-generation/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.\n\nOmitting `parameters` defines a function with an empty parameter list." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling)." } } }, "FunctionShellAction": { "type": "object", "description": "Shell exec action\nExecute a shell command.", "required": [ "commands" ], "properties": { "commands": { "type": "array", "items": { "type": "string" }, "description": "A list of commands to run." }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional timeout in milliseconds for the commands.", "minimum": 0 }, "max_output_length": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional maximum number of characters to return from each command.", "minimum": 0 } } }, "FunctionShellActionParam": { "type": "object", "description": "Commands and limits describing how to run the shell tool call.", "required": [ "commands" ], "properties": { "commands": { "type": "array", "items": { "type": "string" }, "description": "Ordered shell commands for the execution environment to run." }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum wall-clock time in milliseconds to allow the shell commands to run.", "minimum": 0 }, "max_output_length": { "type": [ "integer", "null" ], "format": "int64", "description": "Maximum number of UTF-8 characters to capture from combined stdout and stderr output.", "minimum": 0 } } }, "FunctionShellCall": { "type": "object", "description": "A tool call that executes one or more shell commands in a managed environment.", "required": [ "id", "call_id", "action", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the function shell tool call. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the function shell tool call generated by the model." }, "action": { "$ref": "#/components/schemas/FunctionShellAction", "description": "The shell commands and limits that describe how to run the tool call." }, "status": { "$ref": "#/components/schemas/LocalShellCallStatus", "description": "The status of the shell call. One of `in_progress`, `completed`, or `incomplete`." }, "environment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionShellCallEnvironment", "description": "The environment in which the shell commands were executed." } ] }, "created_by": { "type": [ "string", "null" ], "description": "The ID of the entity that created this tool call." } } }, "FunctionShellCallEnvironment": { "oneOf": [ { "type": "object", "description": "A local computer environment.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/ContainerReferenceResource", "description": "A referenced container." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_reference" ] } } } ], "description": "A referenced container." } ], "description": "The environment for a shell call (response side)." }, "FunctionShellCallItemEnvironment": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/LocalEnvironmentParam", "description": "Use a local computer environment." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local" ] } } } ], "description": "Use a local computer environment." }, { "allOf": [ { "$ref": "#/components/schemas/ContainerReferenceParam", "description": "Reference an existing container by ID." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_reference" ] } } } ], "description": "Reference an existing container by ID." } ], "description": "The environment for a shell call item (request side)." }, "FunctionShellCallItemParam": { "type": "object", "description": "A tool representing a request to execute one or more shell commands.", "required": [ "call_id", "action" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of the shell tool call. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the shell tool call generated by the model." }, "action": { "$ref": "#/components/schemas/FunctionShellActionParam", "description": "The shell commands and limits that describe how to run the tool call." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionShellCallItemStatus", "description": "The status of the shell call. One of `in_progress`, `completed`, or `incomplete`." } ] }, "environment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionShellCallItemEnvironment", "description": "The environment to execute the shell commands in." } ] } } }, "FunctionShellCallItemStatus": { "type": "string", "description": "Status values reported for shell tool calls.", "enum": [ "in_progress", "completed", "incomplete" ] }, "FunctionShellCallOutput": { "type": "object", "description": "The output of a shell tool call that was emitted.", "required": [ "id", "call_id", "output" ], "properties": { "id": { "type": "string", "description": "The unique ID of the shell call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the shell tool call generated by the model." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/FunctionShellCallOutputContent" }, "description": "An array of shell call output contents" }, "max_output_length": { "type": [ "integer", "null" ], "format": "int64", "description": "The maximum length of the shell command output. This is generated by the model and should be\npassed back with the raw output.", "minimum": 0 }, "created_by": { "type": [ "string", "null" ], "description": "The identifier of the actor that created the item." } } }, "FunctionShellCallOutputContent": { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallOutputOutcome", "description": "Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk." }, { "type": "object", "required": [ "stdout", "stderr" ], "properties": { "stdout": { "type": "string", "description": "The standard output that was captured." }, "stderr": { "type": "string", "description": "The standard error output that was captured." }, "created_by": { "type": [ "string", "null" ], "description": "The identifier of the actor that created the item." } } } ], "description": "The content of a shell tool call output that was emitted." }, "FunctionShellCallOutputContentParam": { "type": "object", "description": "Captured stdout and stderr for a portion of a shell tool call output.", "required": [ "stdout", "stderr", "outcome" ], "properties": { "stdout": { "type": "string", "description": "Captured stdout output for this chunk of the shell call." }, "stderr": { "type": "string", "description": "Captured stderr output for this chunk of the shell call." }, "outcome": { "$ref": "#/components/schemas/FunctionShellCallOutputOutcomeParam", "description": "The exit or timeout outcome associated with this chunk." } } }, "FunctionShellCallOutputExitOutcome": { "type": "object", "description": "Indicates that the shell commands finished and returned an exit code.", "required": [ "exit_code" ], "properties": { "exit_code": { "type": "integer", "format": "int32", "description": "Exit code from the shell process." } } }, "FunctionShellCallOutputExitOutcomeParam": { "type": "object", "description": "Indicates that the shell commands finished and returned an exit code.", "required": [ "exit_code" ], "properties": { "exit_code": { "type": "integer", "format": "int32", "description": "The exit code returned by the shell process." } } }, "FunctionShellCallOutputItemParam": { "type": "object", "description": "The streamed output items emitted by a shell tool call.", "required": [ "call_id", "output" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of the shell tool call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the shell tool call generated by the model." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/FunctionShellCallOutputContentParam" }, "description": "Captured chunks of stdout and stderr output, along with their associated outcomes." }, "max_output_length": { "type": [ "integer", "null" ], "format": "int64", "description": "The maximum number of UTF-8 characters captured for this shell call's combined output.", "minimum": 0 } } }, "FunctionShellCallOutputOutcome": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "timeout" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallOutputExitOutcome" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "exit" ] } } } ] } ], "description": "Function shell call outcome" }, "FunctionShellCallOutputOutcomeParam": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "timeout" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallOutputExitOutcomeParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "exit" ] } } } ] } ], "description": "The exit or timeout outcome associated with this chunk." }, "FunctionShellEnvironment": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ContainerAutoParam", "description": "Automatically creates a container for this request." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_auto" ] } } } ], "description": "Automatically creates a container for this request." }, { "allOf": [ { "$ref": "#/components/schemas/LocalEnvironmentParam", "description": "Use a local computer environment." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local" ] } } } ], "description": "Use a local computer environment." }, { "allOf": [ { "$ref": "#/components/schemas/ContainerReferenceParam", "description": "Reference an existing container by ID." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "container_reference" ] } } } ], "description": "Reference an existing container by ID." } ], "description": "The execution environment for a shell tool — container or local." }, "FunctionShellToolParam": { "type": "object", "description": "Parameters for the shell function tool.", "properties": { "environment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FunctionShellEnvironment", "description": "The execution environment for the shell tool." } ] } } }, "FunctionTool": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "parameters": { "type": [ "object", "null" ], "description": "A JSON schema object describing the parameters of the function." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether to enforce strict parameter validation. Default `true`." }, "description": { "type": [ "string", "null" ], "description": "A description of the function. Used by the model to determine whether or not to call the\nfunction." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether this function is deferred and loaded via tool search." } } }, "FunctionToolCall": { "type": "object", "required": [ "arguments", "call_id", "name" ], "properties": { "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model." }, "namespace": { "type": [ "string", "null" ], "description": "The namespace of the function to run." }, "name": { "type": "string", "description": "The name of the function to run." }, "id": { "type": [ "string", "null" ], "description": "The unique ID of the function tool call." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when items are returned via API." } ] } } }, "FunctionToolParam": { "type": "object", "description": "A function tool that can be used within a namespace or with tool search.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function." }, "description": { "type": [ "string", "null" ], "description": "A description of the function." }, "parameters": { "type": [ "object", "null" ], "description": "A JSON schema object describing the parameters of the function." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether to enforce strict parameter validation." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether this function should be deferred and discovered via tool search." } } }, "FunctionType": { "type": "string", "enum": [ "function" ] }, "GrammarSyntax": { "type": "string", "enum": [ "lark", "regex" ] }, "HybridSearch": { "type": "object", "required": [ "embedding_weight", "text_weight" ], "properties": { "embedding_weight": { "type": "number", "format": "float", "description": "The weight of the embedding in the reciprocal ranking fusion." }, "text_weight": { "type": "number", "format": "float", "description": "The weight of the text in the reciprocal ranking fusion." } } }, "ImageDetail": { "type": "string", "enum": [ "auto", "low", "high", "original" ] }, "ImageGenActionEnum": { "type": "string", "description": "Whether to generate a new image or edit an existing image.", "enum": [ "generate", "edit", "auto" ] }, "ImageGenTool": { "type": "object", "description": "Image generation tool definition.", "properties": { "background": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolBackground", "description": "Background type for the generated image. One of `transparent`,\n`opaque`, or `auto`. Default: `auto`." } ] }, "input_fidelity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InputFidelity", "description": "Control how much effort the model will exert to match the style and features, especially facial features,\nof input images. This parameter is only supported for `gpt-image-1`. Unsupported\nfor `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`." } ] }, "input_image_mask": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolInputImageMask", "description": "Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional)." } ] }, "model": { "type": [ "string", "null" ], "description": "The image generation model to use. Default: `gpt-image-1`." }, "moderation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolModeration", "description": "Moderation level for the generated image. Default: `auto`." } ] }, "output_compression": { "type": [ "integer", "null" ], "format": "int32", "description": "Compression level for the output image. Default: 100.", "minimum": 0 }, "output_format": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolOutputFormat", "description": "The output format of the generated image. One of `png`, `webp`, or\n`jpeg`. Default: `png`." } ] }, "partial_images": { "type": [ "integer", "null" ], "format": "int32", "description": "Number of partial images to generate in streaming mode, from 0 (default value) to 3.", "minimum": 0 }, "quality": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolQuality", "description": "The quality of the generated image. One of `low`, `medium`, `high`,\nor `auto`. Default: `auto`." } ] }, "size": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenToolSize", "description": "The size of the generated image. One of `1024x1024`, `1024x1536`,\n`1536x1024`, or `auto`. Default: `auto`." } ] }, "action": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageGenActionEnum", "description": "Whether to generate a new image or edit an existing image. Default: `auto`." } ] } } }, "ImageGenToolBackground": { "type": "string", "enum": [ "transparent", "opaque", "auto" ] }, "ImageGenToolCall": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the image generation call." }, "result": { "type": [ "string", "null" ], "description": "The generated image encoded in base64." }, "status": { "$ref": "#/components/schemas/ImageGenToolCallStatus", "description": "The status of the image generation call." } } }, "ImageGenToolCallStatus": { "type": "string", "enum": [ "in_progress", "completed", "generating", "failed" ] }, "ImageGenToolInputImageMask": { "type": "object", "properties": { "image_url": { "type": [ "string", "null" ], "description": "Base64-encoded mask image." }, "file_id": { "type": [ "string", "null" ], "description": "File ID for the mask image." } } }, "ImageGenToolModeration": { "type": "string", "enum": [ "auto", "low" ] }, "ImageGenToolOutputFormat": { "type": "string", "enum": [ "png", "webp", "jpeg" ] }, "ImageGenToolQuality": { "type": "string", "enum": [ "low", "medium", "high", "auto" ] }, "ImageGenToolSize": { "type": "string", "enum": [ "auto", "1024x1024", "1024x1536", "1536x1024" ] }, "ImageUrl": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Either a URL of the image or the base64 encoded image data." }, "detail": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageDetail", "description": "Specifies the detail level of the image. Learn more in the [Vision guide](https://platform.openai.com/docs/guides/vision/low-or-high-fidelity-image-understanding)." } ] } } }, "IncludeEnum": { "type": "string", "enum": [ "file_search_call.results", "web_search_call.results", "web_search_call.action.sources", "message.input_image.image_url", "computer_call_output.output.image_url", "code_interpreter_call.outputs", "reasoning.encrypted_content", "message.output_text.logprobs" ] }, "IncompleteDetails": { "type": "object", "description": "Details about an incomplete response.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "The reason why the response is incomplete." } } }, "InlineSkillParam": { "type": "object", "description": "An inline skill definition.", "required": [ "name", "description", "source" ], "properties": { "name": { "type": "string", "description": "The name of the skill." }, "description": { "type": "string", "description": "The description of the skill." }, "source": { "$ref": "#/components/schemas/InlineSkillSourceParam", "description": "The inline source for the skill." } } }, "InlineSkillSourceParam": { "type": "object", "description": "An inline skill source (base64-encoded zip).", "required": [ "media_type", "data" ], "properties": { "media_type": { "type": "string", "description": "The media type. Always `\"application/zip\"`." }, "data": { "type": "string", "description": "The base64-encoded skill data." } } }, "InputAudio": { "type": "object", "required": [ "data", "format" ], "properties": { "data": { "type": "string", "description": "Base64 encoded audio data." }, "format": { "$ref": "#/components/schemas/InputAudioFormat", "description": "The format of the encoded audio data. Currently supports \"wav\" and \"mp3\"." } } }, "InputAudioFormat": { "type": "string", "enum": [ "wav", "mp3" ] }, "InputContent": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/InputTextContent", "description": "A text input to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_text" ] } } } ], "description": "A text input to the model." }, { "allOf": [ { "$ref": "#/components/schemas/InputImageContent", "description": "An image input to the model. Learn about\n[image inputs](https://platform.openai.com/docs/guides/vision)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_image" ] } } } ], "description": "An image input to the model. Learn about\n[image inputs](https://platform.openai.com/docs/guides/vision)." }, { "allOf": [ { "$ref": "#/components/schemas/InputFileContent", "description": "A file input to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "input_file" ] } } } ], "description": "A file input to the model." } ], "description": "Parts of a message: text, image, file, or audio." }, "InputFidelity": { "type": "string", "enum": [ "high", "low" ] }, "InputFileContent": { "type": "object", "properties": { "file_data": { "type": [ "string", "null" ], "description": "The content of the file to be sent to the model." }, "file_id": { "type": [ "string", "null" ], "description": "The ID of the file to be sent to the model." }, "file_url": { "type": [ "string", "null" ], "description": "The URL of the file to be sent to the model." }, "filename": { "type": [ "string", "null" ], "description": "The name of the file to be sent to the model." } } }, "InputImageContent": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "$ref": "#/components/schemas/ImageDetail", "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`.\nDefaults to `auto`." }, "file_id": { "type": [ "string", "null" ], "description": "The ID of the file to be sent to the model." }, "image_url": { "type": [ "string", "null" ], "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image\nin a data URL." } } }, "InputItem": { "oneOf": [ { "$ref": "#/components/schemas/ItemReference", "description": "A reference to an existing item by ID.\nHas a required `id` field and optional `type` (can be \"item_reference\" or null).\nMust be tried first as it's the most minimal structure." }, { "$ref": "#/components/schemas/Item", "description": "All structured items with proper type discrimination.\nIncludes InputMessage, OutputMessage, and all tool calls/outputs.\nUses the discriminated `Item` enum for efficient, type-safe deserialization." }, { "$ref": "#/components/schemas/EasyInputMessage", "description": "A simple, user-friendly message input (EasyInputMessage).\nSupports string content and can include assistant role for previous responses.\nMust be tried last as it's the most flexible structure.\n\nA message input to the model with a role indicating instruction following\nhierarchy. Instructions given with the `developer` or `system` role take\nprecedence over instructions given with the `user` role. Messages with the\n`assistant` role are presumed to have been generated by the model in previous\ninteractions." } ], "description": "Input item that can be used in the context for generating a response.\n\nThis represents the OpenAPI `InputItem` schema which is an `anyOf`:\n1. `EasyInputMessage` - Simple, user-friendly message input (can use string content)\n2. `Item` - Structured items with proper type discrimination (including InputMessage, OutputMessage, tool calls)\n3. `ItemReferenceParam` - Reference to an existing item by ID (type can be null)\n\nUses untagged deserialization because these types overlap in structure.\nOrder matters: more specific structures are tried first.\n\n# OpenAPI Specification\nCorresponds to the `InputItem` schema: `anyOf[EasyInputMessage, Item, ItemReferenceParam]`" }, "InputMessage": { "type": "object", "description": "A structured message input to the model (InputMessage in the OpenAPI spec).\n\nThis variant requires structured content (not a simple string) and does not support\nthe `assistant` role (use OutputMessage for that). status is populated when items are returned via API.", "required": [ "content", "role" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/InputContent" }, "description": "A list of one or many input items to the model, containing different content types." }, "role": { "$ref": "#/components/schemas/InputRole", "description": "The role of the message input. One of `user`, `system`, or `developer`.\nNote: `assistant` is NOT allowed here; use OutputMessage instead." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when items are returned via API." } ] } } }, "InputParam": { "oneOf": [ { "type": "string", "description": " A text input to the model, equivalent to a text input with the\n`user` role." }, { "type": "array", "items": { "$ref": "#/components/schemas/InputItem" }, "description": "A list of one or many input items to the model, containing\ndifferent content types." } ] }, "InputRole": { "type": "string", "description": "The role for an input message - can only be `user`, `system`, or `developer`.\nThis type ensures type safety by excluding the `assistant` role (use OutputMessage for that).", "enum": [ "user", "system", "developer" ] }, "InputTextContent": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text input to the model." } } }, "InputTokenDetails": { "type": "object", "required": [ "cached_tokens" ], "properties": { "cached_tokens": { "type": "integer", "format": "int32", "description": "The number of tokens that were retrieved from the cache.\n[More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching).", "minimum": 0 } } }, "Instructions": { "oneOf": [ { "type": "string", "description": "A text input to the model, equivalent to a text input with the `developer` role." }, { "type": "array", "items": { "$ref": "#/components/schemas/InputItem" }, "description": "A list of one or many input items to the model, containing different content types." } ] }, "Item": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MessageItem", "description": "A message (type: \"message\").\nCan represent InputMessage (user/system/developer) or OutputMessage (assistant).\n\nInputMessage:\n A message input to the model with a role indicating instruction following hierarchy.\n Instructions given with the developer or system role take precedence over instructions given with the user role.\nOutputMessage:\n A message output from the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "message" ] } } } ], "description": "A message (type: \"message\").\nCan represent InputMessage (user/system/developer) or OutputMessage (assistant).\n\nInputMessage:\n A message input to the model with a role indicating instruction following hierarchy.\n Instructions given with the developer or system role take precedence over instructions given with the user role.\nOutputMessage:\n A message output from the model." }, { "allOf": [ { "$ref": "#/components/schemas/FileSearchToolCall", "description": "The results of a file search tool call. See the\n[file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_search_call" ] } } } ], "description": "The results of a file search tool call. See the\n[file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information." }, { "allOf": [ { "$ref": "#/components/schemas/ComputerToolCall", "description": "A tool call to a computer use tool. See the\n[computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_call" ] } } } ], "description": "A tool call to a computer use tool. See the\n[computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information." }, { "allOf": [ { "$ref": "#/components/schemas/ComputerCallOutputItemParam", "description": "The output of a computer tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_call_output" ] } } } ], "description": "The output of a computer tool call." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolCall", "description": "The results of a web search tool call. See the\n[web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_call" ] } } } ], "description": "The results of a web search tool call. See the\n[web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionToolCall", "description": "A tool call to run a function. See the\n\n[function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function_call" ] } } } ], "description": "A tool call to run a function. See the\n\n[function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionCallOutputItemParam", "description": "The output of a function tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function_call_output" ] } } } ], "description": "The output of a function tool call." }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchCallItemParam", "description": "A tool search call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_search_call" ] } } } ], "description": "A tool search call." }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchOutputItemParam", "description": "A tool search output." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_search_output" ] } } } ], "description": "A tool search output." }, { "allOf": [ { "$ref": "#/components/schemas/ReasoningItem", "description": "A description of the chain of thought used by a reasoning model while generating\na response. Be sure to include these items in your `input` to the Responses API\nfor subsequent turns of a conversation if you are manually\n[managing context](https://platform.openai.com/docs/guides/conversation-state)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reasoning" ] } } } ], "description": "A description of the chain of thought used by a reasoning model while generating\na response. Be sure to include these items in your `input` to the Responses API\nfor subsequent turns of a conversation if you are manually\n[managing context](https://platform.openai.com/docs/guides/conversation-state)." }, { "allOf": [ { "$ref": "#/components/schemas/CompactionSummaryItemParam", "description": "A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "compaction" ] } } } ], "description": "A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact)." }, { "allOf": [ { "$ref": "#/components/schemas/ImageGenToolCall", "description": "An image generation request made by the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_generation_call" ] } } } ], "description": "An image generation request made by the model." }, { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterToolCall", "description": "A tool call to run code." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "code_interpreter_call" ] } } } ], "description": "A tool call to run code." }, { "allOf": [ { "$ref": "#/components/schemas/LocalShellToolCall", "description": "A tool call to run a command on the local shell." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local_shell_call" ] } } } ], "description": "A tool call to run a command on the local shell." }, { "allOf": [ { "$ref": "#/components/schemas/LocalShellToolCallOutput", "description": "The output of a local shell tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local_shell_call_output" ] } } } ], "description": "The output of a local shell tool call." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallItemParam", "description": "A tool representing a request to execute one or more shell commands." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell_call" ] } } } ], "description": "A tool representing a request to execute one or more shell commands." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallOutputItemParam", "description": "The streamed output items emitted by a shell tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell_call_output" ] } } } ], "description": "The streamed output items emitted by a shell tool call." }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchToolCallItemParam", "description": "A tool call representing a request to create, delete, or update files using diff patches." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch_call" ] } } } ], "description": "A tool call representing a request to create, delete, or update files using diff patches." }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchToolCallOutputItemParam", "description": "The streamed output emitted by an apply patch tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch_call_output" ] } } } ], "description": "The streamed output emitted by an apply patch tool call." }, { "allOf": [ { "$ref": "#/components/schemas/MCPListTools", "description": "A list of tools available on an MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_list_tools" ] } } } ], "description": "A list of tools available on an MCP server." }, { "allOf": [ { "$ref": "#/components/schemas/MCPApprovalRequest", "description": "A request for human approval of a tool invocation." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_approval_request" ] } } } ], "description": "A request for human approval of a tool invocation." }, { "allOf": [ { "$ref": "#/components/schemas/MCPApprovalResponse", "description": "A response to an MCP approval request." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_approval_response" ] } } } ], "description": "A response to an MCP approval request." }, { "allOf": [ { "$ref": "#/components/schemas/MCPToolCall", "description": "An invocation of a tool on an MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_call" ] } } } ], "description": "An invocation of a tool on an MCP server." }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolCallOutput", "description": "The output of a custom tool call from your code, being sent back to the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom_tool_call_output" ] } } } ], "description": "The output of a custom tool call from your code, being sent back to the model." }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolCall", "description": "A call to a custom tool created by the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ] } } } ], "description": "A call to a custom tool created by the model." } ], "description": "Content item used to generate a response.\n\nThis is a properly discriminated union based on the `type` field, using Rust's\ntype-safe enum with serde's tag attribute for efficient deserialization.\n\n# OpenAPI Specification\nCorresponds to the `Item` schema in the OpenAPI spec with a `type` discriminator." }, "ItemReference": { "type": "object", "description": "A reference to an existing item by ID.", "required": [ "id" ], "properties": { "type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemReferenceType", "description": "The type of item to reference. Can be \"item_reference\" or null." } ] }, "id": { "type": "string", "description": "The ID of the item to reference." } } }, "ItemReferenceType": { "type": "string", "enum": [ "item_reference" ] }, "JsonVec": { "type": "array", "items": { "type": "string" } }, "KeyPressAction": { "type": "object", "description": "A keypress action.", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "string" }, "description": "The combination of keys the model is requesting to be pressed.\nThis is an array of strings, each representing a key." } } }, "ListMcpServersResponse": { "type": "object", "required": [ "mcp_servers" ], "properties": { "mcp_servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerResponse" } } } }, "ListMcpsResponse": { "type": "object", "required": [ "mcps" ], "properties": { "mcps": { "type": "array", "items": { "$ref": "#/components/schemas/Mcp" } } } }, "ListModelResponse": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "ListUsersParams": { "type": "object", "description": "List users query parameters. Intentionally omits sort fields (unlike PaginationSortParams)\nbecause user listing is fetched from the auth service which handles its own ordering.", "properties": { "page": { "type": [ "integer", "null" ], "format": "int32", "example": 1, "minimum": 0 }, "page_size": { "type": [ "integer", "null" ], "format": "int32", "example": 10, "minimum": 0 } } }, "LocalEnvironmentParam": { "type": "object", "description": "Uses a local computer environment.", "properties": { "skills": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/LocalSkillParam" }, "description": "An optional list of local skills." } } }, "LocalModelResponse": { "type": "object", "description": "Local model file response", "required": [ "repo", "filename", "snapshot", "model_params" ], "properties": { "repo": { "type": "string" }, "filename": { "type": "string" }, "snapshot": { "type": "string" }, "size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "model_params": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelMetadata", "description": "Model metadata extracted from GGUF file (optional)" } ] } } }, "LocalShellCallStatus": { "type": "string", "description": "Status values reported for function shell tool calls.", "enum": [ "in_progress", "completed", "incomplete" ] }, "LocalShellExecAction": { "type": "object", "description": "Define the shape of a local shell action (exec).", "required": [ "command", "env" ], "properties": { "command": { "type": "array", "items": { "type": "string" }, "description": "The command to run." }, "env": { "type": "object", "description": "Environment variables to set for the command.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional timeout in milliseconds for the command.", "minimum": 0 }, "user": { "type": [ "string", "null" ], "description": "Optional user to run the command as." }, "working_directory": { "type": [ "string", "null" ], "description": "Optional working directory to run the command in." } } }, "LocalShellToolCall": { "type": "object", "required": [ "action", "call_id", "id", "status" ], "properties": { "action": { "$ref": "#/components/schemas/LocalShellExecAction", "description": "Execute a shell command on the server." }, "call_id": { "type": "string", "description": "The unique ID of the local shell tool call generated by the model." }, "id": { "type": "string", "description": "The unique ID of the local shell call." }, "status": { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the local shell call." } } }, "LocalShellToolCallOutput": { "type": "object", "description": "Output from a local shell tool call that you're providing back to the model.", "required": [ "id", "output" ], "properties": { "id": { "type": "string", "description": "The unique ID of the local shell tool call generated by the model." }, "output": { "type": "string", "description": "A JSON string of the output of the local shell tool call." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`." } ] } } }, "LocalSkillParam": { "type": "object", "description": "A local skill available in a local environment.", "required": [ "name", "description", "path" ], "properties": { "name": { "type": "string", "description": "The name of the skill." }, "description": { "type": "string", "description": "The description of the skill." }, "path": { "type": "string", "description": "The path to the directory containing the skill." } } }, "LogProb": { "type": "object", "required": [ "bytes", "logprob", "token", "top_logprobs" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "logprob": { "type": "number", "format": "double" }, "token": { "type": "string" }, "top_logprobs": { "type": "array", "items": { "$ref": "#/components/schemas/TopLogProb" } } } }, "MCPApprovalRequest": { "type": "object", "required": [ "arguments", "id", "name", "server_label" ], "properties": { "arguments": { "type": "string", "description": "JSON string of arguments for the tool." }, "id": { "type": "string", "description": "The unique ID of the approval request." }, "name": { "type": "string", "description": "The name of the tool to run." }, "server_label": { "type": "string", "description": "The label of the MCP server making the request." } } }, "MCPApprovalResponse": { "type": "object", "description": "An MCP approval response that you're providing back to the model.", "required": [ "approval_request_id", "approve" ], "properties": { "approval_request_id": { "type": "string", "description": "The ID of the approval request being answered." }, "approve": { "type": "boolean", "description": "Whether the request was approved." }, "id": { "type": [ "string", "null" ], "description": "The unique ID of the approval response" }, "reason": { "type": [ "string", "null" ], "description": "Optional reason for the decision." } } }, "MCPListTools": { "type": "object", "required": [ "id", "server_label", "tools" ], "properties": { "id": { "type": "string", "description": "The unique ID of the list." }, "server_label": { "type": "string", "description": "The label of the MCP server." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPListToolsTool" }, "description": "The tools available on the server." }, "error": { "type": [ "string", "null" ], "description": "Error message if listing failed." } } }, "MCPListToolsTool": { "type": "object", "required": [ "input_schema", "name" ], "properties": { "input_schema": { "type": "object", "description": "The JSON schema describing the tool's input." }, "name": { "type": "string", "description": "The name of the tool." }, "annotations": { "type": [ "object", "null" ], "description": "Additional annotations about the tool." }, "description": { "type": [ "string", "null" ], "description": "The description of the tool." } } }, "MCPTool": { "type": "object", "required": [ "server_label" ], "properties": { "server_label": { "type": "string", "description": "A label for this MCP server, used to identify it in tool calls." }, "allowed_tools": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MCPToolAllowedTools", "description": "List of allowed tool names or a filter object." } ] }, "authorization": { "type": [ "string", "null" ], "description": "An OAuth access token that can be used with a remote MCP server, either with a custom MCP\nserver URL or a service connector. Your application must handle the OAuth authorization\nflow and provide the token here." }, "connector_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpToolConnectorId", "description": "Identifier for service connectors, like those available in ChatGPT. One of `server_url` or\n`connector_id` must be provided. Learn more about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).\n\nCurrently supported `connector_id` values are:\n- Dropbox: `connector_dropbox`\n- Gmail: `connector_gmail`\n- Google Calendar: `connector_googlecalendar`\n- Google Drive: `connector_googledrive`\n- Microsoft Teams: `connector_microsoftteams`\n- Outlook Calendar: `connector_outlookcalendar`\n- Outlook Email: `connector_outlookemail`\n- SharePoint: `connector_sharepoint`" } ] }, "headers": { "type": [ "object", "null" ], "description": "Optional HTTP headers to send to the MCP server. Use for authentication or other purposes." }, "require_approval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MCPToolRequireApproval", "description": "Specify which of the MCP server's tools require approval." } ] }, "server_description": { "type": [ "string", "null" ], "description": "Optional description of the MCP server, used to provide more context." }, "server_url": { "type": [ "string", "null" ], "description": "The URL for the MCP server. One of `server_url` or `connector_id` must be provided." }, "defer_loading": { "type": [ "boolean", "null" ], "description": "Whether this MCP tool is deferred and discovered via tool search." } } }, "MCPToolAllowedTools": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "description": "A string array of allowed tool names" }, { "$ref": "#/components/schemas/MCPToolFilter", "description": "A filter object to specify which tools are allowed." } ] }, "MCPToolApprovalFilter": { "type": "object", "properties": { "always": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MCPToolFilter", "description": "A list of tools that always require approval." } ] }, "never": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MCPToolFilter", "description": "A list of tools that never require approval." } ] } } }, "MCPToolApprovalSetting": { "type": "string", "enum": [ "always", "never" ] }, "MCPToolCall": { "type": "object", "description": "Output of an MCP server tool invocation.", "required": [ "arguments", "id", "name", "server_label" ], "properties": { "arguments": { "type": "string", "description": "A JSON string of the arguments passed to the tool." }, "id": { "type": "string", "description": "The unique ID of the tool call." }, "name": { "type": "string", "description": "The name of the tool that was run." }, "server_label": { "type": "string", "description": "The label of the MCP server running the tool." }, "approval_request_id": { "type": [ "string", "null" ], "description": "Unique identifier for the MCP tool call approval request. Include this value\nin a subsequent `mcp_approval_response` input to approve or reject the corresponding\ntool call." }, "error": { "type": [ "string", "null" ], "description": "Error message from the call, if any." }, "output": { "type": [ "string", "null" ], "description": "The output from the tool call." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MCPToolCallStatus", "description": "The status of the tool call. One of `in_progress`, `completed`, `incomplete`,\n`calling`, or `failed`." } ] } } }, "MCPToolCallStatus": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "calling", "failed" ] }, "MCPToolFilter": { "type": "object", "properties": { "read_only": { "type": [ "boolean", "null" ], "description": "Indicates whether or not a tool modifies data or is read-only.\nIf an MCP server is annotated with [readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter." }, "tool_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List of allowed tool names." } } }, "MCPToolRequireApproval": { "oneOf": [ { "$ref": "#/components/schemas/MCPToolApprovalFilter", "description": "Specify which of the MCP server's tools require approval. Can be\n`always`, `never`, or a filter object associated with tools\nthat require approval." }, { "$ref": "#/components/schemas/MCPToolApprovalSetting", "description": "Specify a single approval policy for all tools. One of `always` or\n`never`. When set to `always`, all tools will require approval. When\nset to `never`, all tools will not require approval." } ], "description": "Approval policy or filter for MCP tools." }, "Mcp": { "type": "object", "description": "User-owned MCP server instance.", "required": [ "id", "mcp_server", "slug", "name", "enabled", "path", "auth_type", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique instance identifier (UUID)" }, "mcp_server": { "$ref": "#/components/schemas/McpServerInfo", "description": "Server info resolved via JOIN" }, "slug": { "type": "string", "description": "User-defined slug for this instance" }, "name": { "type": "string", "description": "Human-readable name" }, "description": { "type": [ "string", "null" ], "description": "Optional description for this instance" }, "enabled": { "type": "boolean", "description": "Whether this instance is enabled" }, "path": { "type": "string", "description": "MCP proxy path for this instance" }, "auth_type": { "$ref": "#/components/schemas/McpAuthType" }, "auth_config_id": { "type": [ "string", "null" ], "description": "Reference to the auth config (mcp_auth_configs.id)" }, "created_at": { "type": "string", "format": "date-time", "description": "When this instance was created", "example": "2024-11-10T04:52:06.786Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this instance was last updated", "example": "2024-11-10T04:52:06.786Z" } } }, "McpApproval": { "type": "object", "required": [ "url", "status" ], "properties": { "url": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApprovalStatus" }, "instance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpInstance" } ] } } }, "McpAuthConfigParam": { "type": "object", "required": [ "id", "param_type", "param_key" ], "properties": { "id": { "type": "string" }, "param_type": { "$ref": "#/components/schemas/McpAuthParamType" }, "param_key": { "type": "string" } } }, "McpAuthConfigParamInput": { "type": "object", "required": [ "param_type", "param_key" ], "properties": { "param_type": { "$ref": "#/components/schemas/McpAuthParamType" }, "param_key": { "type": "string" } } }, "McpAuthConfigResponse": { "oneOf": [ { "type": "object", "required": [ "id", "name", "mcp_server_id", "created_by", "entries", "created_at", "updated_at", "type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mcp_server_id": { "type": "string" }, "created_by": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/McpAuthConfigParam" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "header" ] } } }, { "type": "object", "required": [ "id", "name", "mcp_server_id", "created_by", "registration_type", "client_id", "authorization_endpoint", "token_endpoint", "has_client_secret", "has_registration_access_token", "created_at", "updated_at", "type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mcp_server_id": { "type": "string" }, "created_by": { "type": "string" }, "registration_type": { "$ref": "#/components/schemas/RegistrationType" }, "client_id": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] }, "client_id_issued_at": { "type": [ "integer", "null" ], "format": "int64" }, "token_endpoint_auth_method": { "type": [ "string", "null" ] }, "has_client_secret": { "type": "boolean" }, "has_registration_access_token": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "oauth" ] } } } ], "description": "Discriminated union response for any type of MCP auth config.\nThe JSON `\"type\"` field determines the variant: `\"header\"` or `\"oauth\"`." }, "McpAuthConfigType": { "type": "string", "enum": [ "header", "oauth" ] }, "McpAuthConfigsListResponse": { "type": "object", "description": "List wrapper for unified auth config responses.", "required": [ "auth_configs" ], "properties": { "auth_configs": { "type": "array", "items": { "$ref": "#/components/schemas/McpAuthConfigResponse" } } } }, "McpAuthParam": { "type": "object", "required": [ "id", "param_type", "param_key", "has_value" ], "properties": { "id": { "type": "string" }, "param_type": { "$ref": "#/components/schemas/McpAuthParamType" }, "param_key": { "type": "string" }, "has_value": { "type": "boolean" } } }, "McpAuthParamInput": { "type": "object", "required": [ "param_type", "param_key", "value" ], "properties": { "param_type": { "$ref": "#/components/schemas/McpAuthParamType" }, "param_key": { "type": "string" }, "value": { "type": "string" } } }, "McpAuthParamType": { "type": "string", "enum": [ "header", "query" ] }, "McpAuthType": { "type": "string", "enum": [ "public", "header", "oauth" ] }, "McpInstance": { "type": "object", "required": [ "id", "path" ], "properties": { "id": { "type": "string" }, "path": { "type": "string", "description": "MCP proxy path for this instance (e.g. `/bodhi/v1/apps/mcps/{id}/mcp`)" } } }, "McpRequest": { "type": "object", "description": "Input for creating or updating an MCP instance.", "required": [ "name", "slug", "enabled" ], "properties": { "name": { "type": "string", "description": "Human-readable name (required)" }, "slug": { "type": "string", "description": "User-defined slug for this instance (1-24 chars, alphanumeric + hyphens)" }, "mcp_server_id": { "type": [ "string", "null" ], "description": "MCP server ID (required for create, ignored for update)" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "enabled": { "type": "boolean", "description": "Whether this instance is enabled" }, "auth_type": { "$ref": "#/components/schemas/McpAuthType", "description": "Authentication type" }, "auth_config_id": { "type": [ "string", "null" ], "description": "Reference to auth config" }, "credentials": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/McpAuthParamInput" }, "description": "Instance-level auth params (values for the auth config's key definitions)" }, "oauth_token_id": { "type": [ "string", "null" ], "description": "OAuth token ID to link to this MCP instance (set after OAuth flow)" } } }, "McpServer": { "type": "object", "description": "Admin-managed MCP server registry entry.\nAdmins/managers register MCP server URLs that users can then create instances of.", "required": [ "id", "url", "name", "enabled", "created_by", "updated_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier (UUID)" }, "url": { "type": "string", "description": "MCP server endpoint URL (trimmed, case-insensitive unique)" }, "name": { "type": "string", "description": "Human-readable display name" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "enabled": { "type": "boolean", "description": "Whether this MCP server is enabled" }, "created_by": { "type": "string", "description": "User who created this entry" }, "updated_by": { "type": "string", "description": "User who last updated this entry" }, "created_at": { "type": "string", "format": "date-time", "description": "When this entry was created", "example": "2024-11-10T04:52:06.786Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this entry was last updated", "example": "2024-11-10T04:52:06.786Z" } } }, "McpServerInfo": { "type": "object", "description": "Minimal MCP server info embedded in MCP instance responses.", "required": [ "id", "url", "name", "enabled" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" } } }, "McpServerRequest": { "type": "object", "description": "Input for creating or updating an MCP server.", "required": [ "url", "name", "enabled" ], "properties": { "url": { "type": "string", "description": "MCP server endpoint URL (trimmed, case-insensitive unique)" }, "name": { "type": "string", "description": "Human-readable display name" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "enabled": { "type": "boolean", "description": "Whether this MCP server is enabled" }, "auth_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateMcpAuthConfigRequest", "description": "Optional auth config to create alongside the server (create only)" } ] } } }, "McpServerResponse": { "allOf": [ { "$ref": "#/components/schemas/McpServer" }, { "type": "object", "required": [ "enabled_mcp_count", "disabled_mcp_count" ], "properties": { "enabled_mcp_count": { "type": "integer", "format": "int64" }, "disabled_mcp_count": { "type": "integer", "format": "int64" }, "auth_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/McpAuthConfigResponse" } ] } } } ], "description": "MCP server response with computed mcp counts and optional auth config." }, "McpServerReviewInfo": { "type": "object", "required": [ "url", "instances" ], "properties": { "url": { "type": "string", "description": "Requested MCP server URL" }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/Mcp" }, "description": "User's MCP instances connected to this server URL" } } }, "McpToolConnectorId": { "type": "string", "enum": [ "connector_dropbox", "connector_gmail", "connector_googlecalendar", "connector_googledrive", "connector_microsoftteams", "connector_outlookcalendar", "connector_outlookemail", "connector_sharepoint" ] }, "Message": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "images": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "MessageItem": { "oneOf": [ { "$ref": "#/components/schemas/OutputMessage", "description": "An output message from the model (role: assistant, has required id & status).\nThis must come first as it has the most specific structure (required id and status fields)." }, { "$ref": "#/components/schemas/InputMessage", "description": "A structured input message (role: user/system/developer, content is `Vec`).\nHas structured content list and optional id/status fields.\n\nA message input to the model with a role indicating instruction following hierarchy.\nInstructions given with the `developer` or `system` role take precedence over instructions\ngiven with the `user` role." } ], "description": "A message item used within the `Item` enum.\n\nBoth InputMessage and OutputMessage have `type: \"message\"`, so we use an untagged\nenum to distinguish them based on their structure:\n- OutputMessage: role=assistant, required id & status fields\n- InputMessage: role=user/system/developer, content is `Vec`, optional id/status\n\nNote: EasyInputMessage is NOT included here - it's a separate variant in `InputItem`,\nnot part of the structured `Item` enum." }, "MessagePhase": { "type": "string", "description": "Labels an `assistant` message as intermediate commentary or the final answer.\nFor models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend\nphase on all assistant messages — dropping it can degrade performance.", "enum": [ "commentary", "final_answer" ] }, "MessageType": { "type": "string", "enum": [ "message" ] }, "Metadata": { "description": "Set of 16 key-value pairs that can be attached to an object.\nThis can be useful for storing additional information about the\nobject in a structured format, and querying for objects via API\nor the dashboard. Keys are strings with a maximum length of 64\ncharacters. Values are strings with a maximum length of 512\ncharacters." }, "Model": { "type": "object", "description": "Describes an OpenAI model offering that can be used with the API.", "required": [ "id", "object", "created", "owned_by" ], "properties": { "id": { "type": "string", "description": "The model identifier, which can be referenced in the API endpoints." }, "object": { "type": "string", "description": "The object type, which is always \"model\"." }, "created": { "type": "integer", "format": "int32", "description": "The Unix timestamp (in seconds) when the model was created.", "minimum": 0 }, "owned_by": { "type": "string", "description": "The organization that owns the model." } } }, "ModelAlias": { "type": "object", "required": [ "alias", "repo", "filename", "snapshot" ], "properties": { "alias": { "type": "string" }, "repo": { "type": "string", "format": "string" }, "filename": { "type": "string" }, "snapshot": { "type": "string" } } }, "ModelAliasResponse": { "type": "object", "description": "Response for auto-discovered model aliases", "required": [ "source", "alias", "repo", "filename", "snapshot" ], "properties": { "source": { "type": "string" }, "alias": { "type": "string" }, "repo": { "type": "string" }, "filename": { "type": "string" }, "snapshot": { "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelMetadata", "description": "Model metadata extracted from GGUF file (optional)" } ] } } }, "ModelArchitecture": { "type": "object", "required": [ "format" ], "properties": { "family": { "type": [ "string", "null" ] }, "parameter_count": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "quantization": { "type": [ "string", "null" ] }, "format": { "type": "string" } } }, "ModelCapabilities": { "type": "object", "required": [ "tools" ], "properties": { "vision": { "type": [ "boolean", "null" ] }, "audio": { "type": [ "boolean", "null" ] }, "thinking": { "type": [ "boolean", "null" ] }, "tools": { "$ref": "#/components/schemas/ToolCapabilities" } } }, "ModelDetails": { "type": "object", "required": [ "format", "family", "parameter_size", "quantization_level" ], "properties": { "parent_model": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "family": { "type": "string" }, "families": { "type": [ "array", "null" ], "items": { "type": "string" } }, "parameter_size": { "type": "string" }, "quantization_level": { "type": "string" } } }, "ModelMetadata": { "type": "object", "description": "Model metadata for API responses", "required": [ "capabilities", "context", "architecture" ], "properties": { "capabilities": { "$ref": "#/components/schemas/ModelCapabilities" }, "context": { "$ref": "#/components/schemas/ContextLimits" }, "architecture": { "$ref": "#/components/schemas/ModelArchitecture" }, "chat_template": { "type": [ "string", "null" ] } } }, "ModelsResponse": { "type": "object", "required": [ "models" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/OllamaModel" } } } }, "MoveParam": { "type": "object", "description": "A mouse move action.", "required": [ "x", "y" ], "properties": { "x": { "type": "integer", "format": "int32", "description": "The x-coordinate to move to." }, "y": { "type": "integer", "format": "int32", "description": "The y-coordinate to move to." } } }, "NamespaceToolParam": { "type": "object", "description": "Groups function/custom tools under a shared namespace.", "required": [ "name", "description", "tools" ], "properties": { "name": { "type": "string", "description": "The namespace name used in tool calls (for example, `crm`)." }, "description": { "type": "string", "description": "A description of the namespace shown to the model." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/NamespaceToolParamTool" }, "description": "The function/custom tools available inside this namespace." } } }, "NamespaceToolParamTool": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionToolParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolParam" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ] } ], "description": "A function or custom tool that belongs to a namespace." }, "NewDownloadRequest": { "type": "object", "description": "Request for creating a new download request", "required": [ "repo", "filename" ], "properties": { "repo": { "type": "string", "description": "HuggingFace repository name in format 'username/repository-name'", "example": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF", "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$" }, "filename": { "type": "string", "description": "Model file name to download (typically .gguf format)", "example": "mistral-7b-instruct-v0.1.Q4_K_M.gguf", "pattern": ".*\\.(gguf|bin|safetensors)$" } }, "example": { "filename": "mistral-7b-instruct-v0.1.Q4_K_M.gguf", "repo": "TheBloke/Mistral-7B-Instruct-v0.1-GGUF" } }, "OAIRequestParams": { "type": "object", "properties": { "frequency_penalty": { "type": [ "number", "null" ], "format": "float" }, "max_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "presence_penalty": { "type": [ "number", "null" ], "format": "float" }, "seed": { "type": [ "integer", "null" ], "format": "int64" }, "stop": { "type": "array", "items": { "type": "string" } }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "top_p": { "type": [ "number", "null" ], "format": "float" }, "user": { "type": [ "string", "null" ] } } }, "OAuthDiscoverAsRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "OAuthDiscoverAsResponse": { "type": "object", "required": [ "authorization_endpoint", "token_endpoint" ], "properties": { "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "scopes_supported": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "OAuthDiscoverMcpRequest": { "type": "object", "required": [ "mcp_server_url" ], "properties": { "mcp_server_url": { "type": "string" } } }, "OAuthDiscoverMcpResponse": { "type": "object", "properties": { "authorization_endpoint": { "type": [ "string", "null" ] }, "token_endpoint": { "type": [ "string", "null" ] }, "registration_endpoint": { "type": [ "string", "null" ] }, "scopes_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "resource": { "type": [ "string", "null" ] }, "authorization_server_url": { "type": [ "string", "null" ] } } }, "OAuthLoginRequest": { "type": "object", "required": [ "redirect_uri" ], "properties": { "redirect_uri": { "type": "string" } } }, "OAuthLoginResponse": { "type": "object", "required": [ "authorization_url" ], "properties": { "authorization_url": { "type": "string" } } }, "OAuthTokenExchangeRequest": { "type": "object", "required": [ "code", "redirect_uri", "state" ], "properties": { "mcp_id": { "type": [ "string", "null" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "state": { "type": "string" } } }, "OAuthTokenResponse": { "type": "object", "required": [ "id", "auth_config_id", "has_refresh_token", "user_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "mcp_id": { "type": [ "string", "null" ] }, "auth_config_id": { "type": "string" }, "scopes_granted": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "integer", "null" ], "format": "int64" }, "has_refresh_token": { "type": "boolean" }, "user_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "OllamaError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "OllamaModel": { "type": "object", "required": [ "model", "modified_at", "size", "digest", "details" ], "properties": { "model": { "type": "string" }, "modified_at": { "type": "integer", "format": "int32", "minimum": 0 }, "size": { "type": "integer", "format": "int64" }, "digest": { "type": "string" }, "details": { "$ref": "#/components/schemas/ModelDetails" } } }, "OpenAIApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorBody", "description": "Error details following OpenAI API error format" } }, "example": { "error": { "code": "validation_error", "message": "Validation failed: name is required", "param": "name", "type": "invalid_request_error" } } }, "Options": { "type": "object", "properties": { "num_keep": { "type": [ "integer", "null" ], "format": "int32" }, "seed": { "type": [ "integer", "null" ], "format": "int64" }, "num_predict": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "top_k": { "type": [ "integer", "null" ], "format": "int32" }, "top_p": { "type": [ "number", "null" ], "format": "float" }, "tfs_z": { "type": [ "number", "null" ], "format": "float" }, "typical_p": { "type": [ "number", "null" ], "format": "float" }, "repeat_last_n": { "type": [ "integer", "null" ], "format": "int32" }, "temperature": { "type": [ "number", "null" ], "format": "float" }, "repeat_penalty": { "type": [ "number", "null" ], "format": "float" }, "presence_penalty": { "type": [ "number", "null" ], "format": "float" }, "frequency_penalty": { "type": [ "number", "null" ], "format": "float" }, "mirostat": { "type": [ "number", "null" ], "format": "float" }, "mirostat_tau": { "type": [ "number", "null" ], "format": "float" }, "mirostat_eta": { "type": [ "number", "null" ], "format": "float" }, "penalize_newline": { "type": [ "boolean", "null" ] }, "stop": { "type": [ "array", "null" ], "items": { "type": "string" } }, "numa": { "type": [ "boolean", "null" ] }, "num_ctx": { "type": [ "integer", "null" ], "format": "int32" }, "num_batch": { "type": [ "integer", "null" ], "format": "int32" }, "num_gpu": { "type": [ "integer", "null" ], "format": "int32" }, "main_gpu": { "type": [ "integer", "null" ], "format": "int32" }, "low_vram": { "type": [ "boolean", "null" ] }, "f16_kv": { "type": [ "boolean", "null" ] }, "logits_all": { "type": [ "boolean", "null" ] }, "vocab_only": { "type": [ "boolean", "null" ] }, "use_mmap": { "type": [ "boolean", "null" ] }, "use_mlock": { "type": [ "boolean", "null" ] }, "num_thread": { "type": [ "integer", "null" ], "format": "int32" } } }, "OutputItem": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutputMessage", "description": "An output message from the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "message" ] } } } ], "description": "An output message from the model." }, { "allOf": [ { "$ref": "#/components/schemas/FileSearchToolCall", "description": "The results of a file search tool call. See the\n[file search guide](https://platform.openai.com/docs/guides/tools-file-search)\nfor more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_search_call" ] } } } ], "description": "The results of a file search tool call. See the\n[file search guide](https://platform.openai.com/docs/guides/tools-file-search)\nfor more information." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionToolCall", "description": "A tool call to run a function. See the\n[function calling guide](https://platform.openai.com/docs/guides/function-calling)\nfor more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function_call" ] } } } ], "description": "A tool call to run a function. See the\n[function calling guide](https://platform.openai.com/docs/guides/function-calling)\nfor more information." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchToolCall", "description": "The results of a web search tool call. See the\n[web search guide](https://platform.openai.com/docs/guides/tools-web-search)\nfor more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_call" ] } } } ], "description": "The results of a web search tool call. See the\n[web search guide](https://platform.openai.com/docs/guides/tools-web-search)\nfor more information." }, { "allOf": [ { "$ref": "#/components/schemas/ComputerToolCall", "description": "A tool call to a computer use tool. See the\n[computer use guide](https://platform.openai.com/docs/guides/tools-computer-use)\nfor more information." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_call" ] } } } ], "description": "A tool call to a computer use tool. See the\n[computer use guide](https://platform.openai.com/docs/guides/tools-computer-use)\nfor more information." }, { "allOf": [ { "$ref": "#/components/schemas/ReasoningItem", "description": "A description of the chain of thought used by a reasoning model while generating\na response. Be sure to include these items in your `input` to the Responses API for\nsubsequent turns of a conversation if you are manually\n[managing context](https://platform.openai.com/docs/guides/conversation-state)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reasoning" ] } } } ], "description": "A description of the chain of thought used by a reasoning model while generating\na response. Be sure to include these items in your `input` to the Responses API for\nsubsequent turns of a conversation if you are manually\n[managing context](https://platform.openai.com/docs/guides/conversation-state)." }, { "allOf": [ { "$ref": "#/components/schemas/CompactionBody", "description": "A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "compaction" ] } } } ], "description": "A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact)." }, { "allOf": [ { "$ref": "#/components/schemas/ImageGenToolCall", "description": "An image generation request made by the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_generation_call" ] } } } ], "description": "An image generation request made by the model." }, { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterToolCall", "description": "A tool call to run code." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "code_interpreter_call" ] } } } ], "description": "A tool call to run code." }, { "allOf": [ { "$ref": "#/components/schemas/LocalShellToolCall", "description": "A tool call to run a command on the local shell." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local_shell_call" ] } } } ], "description": "A tool call to run a command on the local shell." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCall", "description": "A tool call that executes one or more shell commands in a managed environment." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell_call" ] } } } ], "description": "A tool call that executes one or more shell commands in a managed environment." }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellCallOutput", "description": "The output of a shell tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell_call_output" ] } } } ], "description": "The output of a shell tool call." }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchToolCall", "description": "A tool call that applies file diffs by creating, deleting, or updating files." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch_call" ] } } } ], "description": "A tool call that applies file diffs by creating, deleting, or updating files." }, { "allOf": [ { "$ref": "#/components/schemas/ApplyPatchToolCallOutput", "description": "The output emitted by an apply patch tool call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch_call_output" ] } } } ], "description": "The output emitted by an apply patch tool call." }, { "allOf": [ { "$ref": "#/components/schemas/MCPToolCall", "description": "An invocation of a tool on an MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_call" ] } } } ], "description": "An invocation of a tool on an MCP server." }, { "allOf": [ { "$ref": "#/components/schemas/MCPListTools", "description": "A list of tools available on an MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_list_tools" ] } } } ], "description": "A list of tools available on an MCP server." }, { "allOf": [ { "$ref": "#/components/schemas/MCPApprovalRequest", "description": "A request for human approval of a tool invocation." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp_approval_request" ] } } } ], "description": "A request for human approval of a tool invocation." }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolCall", "description": "A call to a custom tool created by the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ] } } } ], "description": "A call to a custom tool created by the model." }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchCall", "description": "A tool search call." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_search_call" ] } } } ], "description": "A tool search call." }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchOutput", "description": "A tool search output." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_search_output" ] } } } ], "description": "A tool search output." } ], "description": "Output item" }, "OutputMessage": { "type": "object", "description": "A message generated by the model.", "required": [ "content", "id", "role", "status" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/OutputMessageContent" }, "description": "The content of the output message." }, "id": { "type": "string", "description": "The unique ID of the output message." }, "role": { "$ref": "#/components/schemas/AssistantRole", "description": "The role of the output message. Always `assistant`." }, "phase": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessagePhase", "description": "Labels this assistant message as intermediate commentary (`commentary`) or\nthe final answer (`final_answer`)." } ] }, "status": { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API." } } }, "OutputMessageContent": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/OutputTextContent", "description": "A text output from the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "output_text" ] } } } ], "description": "A text output from the model." }, { "allOf": [ { "$ref": "#/components/schemas/RefusalContent", "description": "A refusal from the model." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "refusal" ] } } } ], "description": "A refusal from the model." } ] }, "OutputStatus": { "type": "string", "description": "Status of input/output items.", "enum": [ "in_progress", "completed", "incomplete" ] }, "OutputTextContent": { "type": "object", "description": "A simple text output from the model.", "required": [ "annotations", "text" ], "properties": { "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" }, "description": "The annotations of the text output." }, "logprobs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/LogProb" } }, "text": { "type": "string", "description": "The text output from the model." } } }, "OutputTokenDetails": { "type": "object", "required": [ "reasoning_tokens" ], "properties": { "reasoning_tokens": { "type": "integer", "format": "int32", "description": "The number of reasoning tokens.", "minimum": 0 } } }, "PaginatedAliasResponse": { "type": "object", "description": "Paginated list of all model aliases (user, model, and API)", "required": [ "data", "total", "page", "page_size" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AliasResponse" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 0 }, "page_size": { "type": "integer", "minimum": 0 } } }, "PaginatedDownloadResponse": { "type": "object", "description": "Paginated list of download requests", "required": [ "data", "total", "page", "page_size" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadRequest" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 0 }, "page_size": { "type": "integer", "minimum": 0 } } }, "PaginatedLocalModelResponse": { "type": "object", "description": "Paginated list of local model files", "required": [ "data", "total", "page", "page_size" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LocalModelResponse" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 0 }, "page_size": { "type": "integer", "minimum": 0 } } }, "PaginatedTokenResponse": { "type": "object", "required": [ "data", "total", "page", "page_size" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TokenDetail" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 0 }, "page_size": { "type": "integer", "minimum": 0 } } }, "PaginatedUserAccessResponse": { "type": "object", "description": "Paginated response for access requests", "required": [ "requests", "total", "page", "page_size" ], "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/UserAccessRequest" }, "description": "List of access requests" }, "total": { "type": "integer", "description": "Total number of requests", "minimum": 0 }, "page": { "type": "integer", "description": "Current page number", "minimum": 0 }, "page_size": { "type": "integer", "description": "Number of items per page", "minimum": 0 } }, "example": { "page": 1, "page_size": 20, "requests": [ { "created_at": "2024-01-01T12:00:00Z", "id": "01HXXXXXX", "status": "pending", "updated_at": "2024-01-01T12:00:00Z", "user_id": "auth0|123", "username": "user@example.com" } ], "total": 1 } }, "PaginatedUserAliasResponse": { "type": "object", "description": "Paginated list of user-defined model aliases", "required": [ "data", "total", "page", "page_size" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserAliasResponse" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 0 }, "page_size": { "type": "integer", "minimum": 0 } } }, "PaginationSortParams": { "type": "object", "description": "Query parameters for pagination and sorting", "properties": { "page": { "type": "integer", "description": "Page number (1-based indexing)", "example": 1, "minimum": 1 }, "page_size": { "type": "integer", "description": "Number of items to return per page (maximum 100)", "example": 30, "maximum": 100, "minimum": 1 }, "sort": { "type": [ "string", "null" ], "description": "Field to sort by. Common values: repo, filename, size, updated_at, snapshot, created_at", "example": "updated_at" }, "sort_order": { "type": "string", "description": "Sort order: 'asc' for ascending, 'desc' for descending", "example": "desc", "pattern": "^(asc|desc)$" } } }, "PingResponse": { "type": "object", "description": "Response to the ping endpoint", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Simple ping response message", "example": "pong" } }, "example": { "message": "pong" } }, "PredictionContent": { "oneOf": [ { "type": "object", "description": "The type of the predicted content you want to provide. This type is\ncurrently always `content`.", "required": [ "content", "type" ], "properties": { "content": { "$ref": "#/components/schemas/PredictionContentContent", "description": "The type of the predicted content you want to provide. This type is\ncurrently always `content`." }, "type": { "type": "string", "enum": [ "content" ] } } } ], "description": "Static predicted output content, such as the content of a text file that is being regenerated." }, "PredictionContentContent": { "oneOf": [ { "type": "string", "description": "The content used for a Predicted Output. This is often the text of a file you are regenerating with minor changes." }, { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionRequestMessageContentPartText" }, "description": "An array of content parts with a defined type. Supported options differ based on the [model](https://platform.openai.com/docs/models) being used to generate the response. Can contain text inputs." } ], "description": "The content that should be matched when generating a model response. If generated tokens would match this content, the entire model response can be returned much more quickly." }, "Prompt": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the prompt template to use." }, "version": { "type": [ "string", "null" ], "description": "Optional version of the prompt template." }, "variables": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponsePromptVariables", "description": "Optional map of values to substitute in for variables in your\nprompt. The substitution values can either be strings, or other\nResponse input types like images or files." } ] } } }, "PromptCacheRetention": { "type": "string", "description": "The retention policy for the prompt cache.", "enum": [ "in_memory", "24h" ] }, "PromptTokensDetails": { "type": "object", "description": "Breakdown of tokens used in a completion.", "properties": { "audio_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Audio input tokens present in the prompt.", "minimum": 0 }, "cached_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Cached tokens present in the prompt.", "minimum": 0 } } }, "QueueStatusResponse": { "type": "object", "description": "Response for queue status operations", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Queue status (\"idle\" or \"processing\")" } } }, "RankVersionType": { "type": "string", "enum": [ "auto", "default-2024-11-15" ] }, "RankingOptions": { "type": "object", "description": "Options for search result ranking.", "required": [ "ranker" ], "properties": { "hybrid_search": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HybridSearch", "description": "Weights that control how reciprocal rank fusion balances semantic embedding matches versus\nsparse keyword matches when hybrid search is enabled." } ] }, "ranker": { "$ref": "#/components/schemas/RankVersionType", "description": "The ranker to use for the file search." }, "score_threshold": { "type": [ "number", "null" ], "format": "float", "description": "The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will\nattempt to return only the most relevant results, but may return fewer results." } } }, "Reasoning": { "type": "object", "description": "o-series reasoning settings.", "properties": { "effort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningEffort", "description": "Constrains effort on reasoning for\n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently supported values are `minimal`, `low`, `medium`, and `high`. Reducing\nreasoning effort can result in faster responses and fewer tokens used\non reasoning in a response.\n\nNote: The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort." } ] }, "summary": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningSummary", "description": "A summary of the reasoning performed by the model. This can be\nuseful for debugging and understanding the model's reasoning process.\nOne of `auto`, `concise`, or `detailed`.\n\n`concise` is supported for `computer-use-preview` models and all reasoning models after\n`gpt-5`." } ] } } }, "ReasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] }, "ReasoningItem": { "type": "object", "description": "A reasoning item representing the model's chain of thought, including summary paragraphs.", "required": [ "id", "summary" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the reasoning content." }, "summary": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryPart" }, "description": "Reasoning summary content." }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ReasoningTextContent" }, "description": "Reasoning text content." }, "encrypted_content": { "type": [ "string", "null" ], "description": "The encrypted content of the reasoning item - populated when a response is generated with\n`reasoning.encrypted_content` in the `include` parameter." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\nPopulated when items are returned via API." } ] } } }, "ReasoningSummary": { "type": "string", "enum": [ "auto", "concise", "detailed" ] }, "ReasoningTextContent": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The reasoning text from the model." } } }, "RedirectResponse": { "type": "object", "required": [ "location" ], "properties": { "location": { "type": "string", "description": "The URL to redirect to (OAuth authorization URL or application home page)", "example": "https://oauth.example.com/auth?client_id=test&redirect_uri=..." } }, "example": { "location": "https://oauth.example.com/auth?client_id=test&redirect_uri=..." } }, "RefreshRequest": { "oneOf": [ { "type": "object", "description": "Bulk async refresh for all models - Request: {\"source\": \"all\"}", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "all" ] } } }, { "type": "object", "description": "Single sync refresh for specific model - Request: {\"source\": \"model\", \"repo\": \"...\", \"filename\": \"...\", \"snapshot\": \"...\"}", "required": [ "repo", "filename", "snapshot", "source" ], "properties": { "repo": { "type": "string", "description": "Repository in format \"user/repo\"", "example": "bartowski/Qwen2.5-3B-Instruct-GGUF" }, "filename": { "type": "string", "description": "Filename of the GGUF model", "example": "Qwen2.5-3B-Instruct-Q4_K_M.gguf" }, "snapshot": { "type": "string", "description": "Snapshot/commit identifier", "example": "8ba1c3c3ee94ba4b86ff92a749ae687dc41fce3f" }, "source": { "type": "string", "enum": [ "model" ] } } } ], "description": "Refresh request - discriminated union by source field" }, "RefreshResponse": { "type": "object", "description": "Response for metadata refresh operations", "required": [ "num_queued" ], "properties": { "num_queued": { "type": "string", "description": "Number of models queued (\"all\" for bulk refresh, \"1\" for single)" }, "alias": { "type": [ "string", "null" ], "description": "Model alias (only for single model refresh)" } } }, "RefreshSource": { "type": "string", "description": "Source type discriminator for refresh requests", "enum": [ "all", "model" ] }, "RefusalContent": { "type": "object", "description": "A refusal explanation from the model.", "required": [ "refusal" ], "properties": { "refusal": { "type": "string", "description": "The refusal explanation from the model." } } }, "RegistrationType": { "type": "string", "description": "OAuth 2.1 registration type: pre-registered client or dynamic client registration (DCR).", "enum": [ "pre_registered", "dynamic_registration" ] }, "RequestedMcpServer": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "RequestedResources": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/RequestedResourcesV1" }, { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "enum": [ "1" ] } } } ] } ], "description": "Versioned envelope for requested resources.\nThe `version` tag is mandatory — clients must specify which version they are using." }, "RequestedResourcesV1": { "type": "object", "properties": { "mcp_servers": { "type": "array", "items": { "$ref": "#/components/schemas/RequestedMcpServer" } } } }, "ResourceRole": { "type": "string", "enum": [ "resource_anonymous", "resource_guest", "resource_user", "resource_power_user", "resource_manager", "resource_admin" ] }, "Response": { "type": "object", "description": "The complete response returned by the Responses API.", "required": [ "created_at", "id", "model", "object", "output", "status" ], "properties": { "background": { "type": [ "boolean", "null" ], "description": "Whether to run the model response in the background.\n[Learn more](https://platform.openai.com/docs/guides/background)." }, "billing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Billing", "description": "Billing information for the response." } ] }, "conversation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Conversation", "description": "The conversation that this response belongs to. Input items and output\nitems from this response are automatically added to this conversation." } ] }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp (in seconds) when this Response was created.", "minimum": 0 }, "completed_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp (in seconds) of when this Response was completed.\nOnly present when the status is `completed`.", "minimum": 0 }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ErrorObject", "description": "An error object returned when the model fails to generate a Response." } ] }, "id": { "type": "string", "description": "Unique identifier for this response." }, "incomplete_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IncompleteDetails", "description": "Details about why the response is incomplete, if any." } ] }, "instructions": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Instructions", "description": "A system (or developer) message inserted into the model's context.\n\nWhen using along with `previous_response_id`, the instructions from a previous response\nwill not be carried over to the next response. This makes it simple to swap out\nsystem (or developer) messages in new responses." } ] }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "An upper bound for the number of tokens that can be generated for a response,\nincluding visible output tokens and\n[reasoning tokens](https://platform.openai.com/docs/guides/reasoning).", "minimum": 0 }, "metadata": { "type": [ "object", "null" ], "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard.\n\nKeys are strings with a maximum length of 64 characters. Values are strings\nwith a maximum length of 512 characters.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "model": { "type": "string", "description": "Model ID used to generate the response, like gpt-4o or o3. OpenAI offers a\nwide range of models with different capabilities, performance characteristics,\nand price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models." }, "object": { "type": "string", "description": "The object type of this resource - always set to `response`." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/OutputItem" }, "description": "An array of content items generated by the model.\n\n- The length and order of items in the output array is dependent on the model's response.\n- Rather than accessing the first item in the output array and assuming it's an assistant\n message with the content generated by the model, you might consider using\n the `output_text` property where supported in SDKs." }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "SDK-only convenience property that contains the aggregated text output from all\n`output_text` items in the `output` array, if any are present.\nSupported in the Python and JavaScript SDKs.\nWhether to allow the model to run tool calls in parallel." }, "previous_response_id": { "type": [ "string", "null" ], "description": "The unique ID of the previous response to the model. Use this to create multi-turn conversations.\nLearn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state).\nCannot be used in conjunction with `conversation`." }, "prompt": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Prompt", "description": "Reference to a prompt template and its variables.\n[Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts)." } ] }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces\nthe `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching)." }, "prompt_cache_retention": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PromptCacheRetention", "description": "The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching,\nwhich keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn\nmore](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention)." } ] }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Reasoning", "description": "**gpt-5 and o-series models only**\nConfiguration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning)." } ] }, "safety_identifier": { "type": [ "string", "null" ], "description": "A stable identifier used to help detect users of your application that may be violating OpenAI's\nusage policies.\n\nThe IDs should be a string that uniquely identifies each user. We recommend hashing their username\nor email address, in order to avoid sending us any identifying information. [Learn\nmore](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers)." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Specifies the processing type used for serving the request.\n- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.\n- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.\n- If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.\n- When not set, the default behavior is 'auto'.\n\nWhen the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter." } ] }, "status": { "$ref": "#/components/schemas/Status", "description": "The status of the response generation.\nOne of `completed`, `failed`, `in_progress`, `cancelled`, `queued`, or `incomplete`." }, "temperature": { "type": [ "number", "null" ], "format": "float", "description": "What sampling temperature was used, between 0 and 2. Higher values like 0.8 make\noutputs more random, lower values like 0.2 make output more focused and deterministic.\n\nWe generally recommend altering this or `top_p` but not both." }, "text": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseTextParam", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](https://platform.openai.com/docs/guides/text)\n- [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)" } ] }, "tool_choice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolChoiceParam", "description": "How the model should select which tool (or tools) to use when generating\na response. See the `tools` parameter to see how to specify which tools\nthe model can call." } ] }, "tools": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Tool" }, "description": "An array of tools the model may call while generating a response. You\ncan specify which tool to use by setting the `tool_choice` parameter.\n\nWe support the following categories of tools:\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search)\n or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about\n [built-in tools](https://platform.openai.com/docs/guides/tools).\n- **MCP Tools**: Integrations with third-party systems via custom MCP servers\n or predefined connectors such as Google Drive and SharePoint. Learn more about\n [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp).\n- **Function calls (custom tools)**: Functions that are defined by you,\n enabling the model to call your own code with strongly typed arguments\n and outputs. Learn more about\n [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use\n custom tools to call your own code." }, "top_logprobs": { "type": [ "integer", "null" ], "format": "int32", "description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each\ntoken position, each with an associated log probability.", "minimum": 0 }, "top_p": { "type": [ "number", "null" ], "format": "float", "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability\nmass. So 0.1 means only the tokens comprising the top 10% probability mass\nare considered.\n\nWe generally recommend altering this or `temperature` but not both." }, "truncation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Truncation", "description": "The truncation strategy to use for the model response.\n - `auto`: If the input to this Response exceeds\n the model's context window size, the model will truncate the\n response to fit the context window by dropping items from the beginning of the conversation.\n - `disabled` (default): If the input size will exceed the context window\n size for a model, the request will fail with a 400 error." } ] }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResponseUsage", "description": "Represents token usage details including input tokens, output tokens,\na breakdown of output tokens, and the total tokens used." } ] } } }, "ResponseFormat": { "oneOf": [ { "type": "object", "description": "The type of response format being defined: `text`", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "description": "The type of response format being defined: `json_object`", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "json_object" ] } } }, { "type": "object", "description": "The type of response format being defined: `json_schema`", "required": [ "json_schema", "type" ], "properties": { "json_schema": { "$ref": "#/components/schemas/ResponseFormatJsonSchema" }, "type": { "type": "string", "enum": [ "json_schema" ] } } } ] }, "ResponseFormatJsonSchema": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "A description of what the response format is for, used by the model to determine how to respond in the format." }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "schema": { "type": [ "object", "null" ], "description": "The schema for the response format, described as a JSON Schema object.\nLearn how to build JSON schemas [here](https://json-schema.org/)." }, "strict": { "type": [ "boolean", "null" ], "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`. To learn more, read the [Structured Outputs\nguide](https://platform.openai.com/docs/guides/structured-outputs)." } } }, "ResponseModalities": { "type": "string", "description": "Output types that you would like the model to generate for this request.\n\nMost models are capable of generating text, which is the default: `[\"text\"]`\n\nThe `gpt-4o-audio-preview` model can also be used to [generate\naudio](https://platform.openai.com/docs/guides/audio). To request that this model generate both text and audio responses, you can use: `[\"text\", \"audio\"]`", "enum": [ "text", "audio" ] }, "ResponsePromptVariables": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/InputContent" }, { "type": "object" } ] }, "ResponseStreamOptions": { "type": "object", "properties": { "include_obfuscation": { "type": [ "boolean", "null" ], "description": "When true, stream obfuscation will be enabled. Stream obfuscation adds\nrandom characters to an `obfuscation` field on streaming delta events to\nnormalize payload sizes as a mitigation to certain side-channel attacks.\nThese obfuscation fields are included by default, but add a small amount\nof overhead to the data stream. You can set `include_obfuscation` to\nfalse to optimize for bandwidth if you trust the network links between\nyour application and the OpenAI API." } } }, "ResponseTextParam": { "type": "object", "description": "Configuration for text response format.", "required": [ "format" ], "properties": { "format": { "$ref": "#/components/schemas/TextResponseFormatConfiguration", "description": "An object specifying the format that the model must output.\n\nConfiguring `{ \"type\": \"json_schema\" }` enables Structured Outputs,\nwhich ensures the model will match your supplied JSON schema. Learn more in the\n[Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).\n\nThe default format is `{ \"type\": \"text\" }` with no additional options.\n\n**Not recommended for gpt-4o and newer models:**\n\nSetting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which\nensures the message the model generates is valid JSON. Using `json_schema`\nis preferred for models that support it." }, "verbosity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Verbosity", "description": "Constrains the verbosity of the model's response. Lower values will result in\nmore concise responses, while higher values will result in more verbose responses.\n\nCurrently supported values are `low`, `medium`, and `high`." } ] } } }, "ResponseUsage": { "type": "object", "description": "Usage statistics for a response.", "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int32", "description": "The number of input tokens.", "minimum": 0 }, "input_tokens_details": { "$ref": "#/components/schemas/InputTokenDetails", "description": "A detailed breakdown of the input tokens." }, "output_tokens": { "type": "integer", "format": "int32", "description": "The number of output tokens.", "minimum": 0 }, "output_tokens_details": { "$ref": "#/components/schemas/OutputTokenDetails", "description": "A detailed breakdown of the output tokens." }, "total_tokens": { "type": "integer", "format": "int32", "description": "The total number of tokens used.", "minimum": 0 } } }, "Role": { "type": "string", "description": "Role of messages in the API.", "enum": [ "user", "assistant", "system", "developer" ] }, "ScrollParam": { "type": "object", "description": "A scroll action.", "required": [ "scroll_x", "scroll_y", "x", "y" ], "properties": { "scroll_x": { "type": "integer", "format": "int32", "description": "The horizontal scroll distance." }, "scroll_y": { "type": "integer", "format": "int32", "description": "The vertical scroll distance." }, "x": { "type": "integer", "format": "int32", "description": "The x-coordinate where the scroll occurred." }, "y": { "type": "integer", "format": "int32", "description": "The y-coordinate where the scroll occurred." } } }, "SearchContentType": { "type": "string", "description": "The type of content to search for.", "enum": [ "text", "image" ] }, "ServiceTier": { "type": "string", "enum": [ "auto", "default", "flex", "scale", "priority" ] }, "SettingInfo": { "type": "object", "required": [ "key", "current_value", "default_value", "source", "metadata" ], "properties": { "key": { "type": "string" }, "current_value": {}, "default_value": {}, "source": { "$ref": "#/components/schemas/SettingSource" }, "metadata": { "$ref": "#/components/schemas/SettingMetadata" } } }, "SettingMetadata": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string" ] } } }, { "type": "object", "required": [ "min", "max", "type" ], "properties": { "min": { "type": "integer", "format": "int64" }, "max": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "number" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "boolean" ] } } }, { "type": "object", "required": [ "options", "type" ], "properties": { "options": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "option" ] } } } ] }, "SettingSource": { "type": "string", "enum": [ "system", "command_line", "environment", "database", "settings_file", "default" ] }, "SetupRequest": { "type": "object", "description": "Request to setup the application in authenticated mode", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Server name for identification (minimum 10 characters)", "example": "My Bodhi Server", "maxLength": 100, "minLength": 10 }, "description": { "type": [ "string", "null" ], "description": "Optional description of the server's purpose", "example": "My personal AI server", "maxLength": 500 } }, "example": { "description": "My personal AI server", "name": "My Bodhi Server" } }, "SetupResponse": { "type": "object", "description": "Response containing the updated application status after setup", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/AppStatus", "description": "New application status after successful setup" } }, "example": { "status": "resource_admin" } }, "ShowRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "ShowResponse": { "type": "object", "required": [ "details", "license", "model_info", "modelfile", "modified_at", "parameters", "template" ], "properties": { "details": { "$ref": "#/components/schemas/ModelDetails" }, "license": { "type": "string" }, "model_info": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "modelfile": { "type": "string" }, "modified_at": { "type": "integer", "format": "int32", "minimum": 0 }, "parameters": { "type": "string" }, "template": { "type": "string" } } }, "SkillParam": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SkillReferenceParam", "description": "Reference a skill by ID." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "skill_reference" ] } } } ], "description": "Reference a skill by ID." }, { "allOf": [ { "$ref": "#/components/schemas/InlineSkillParam", "description": "Provide an inline skill definition." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "inline" ] } } } ], "description": "Provide an inline skill definition." } ], "description": "A skill parameter — either a reference or inline definition." }, "SkillReferenceParam": { "type": "object", "description": "A skill referenced by ID.", "required": [ "skill_id" ], "properties": { "skill_id": { "type": "string", "description": "The ID of the skill to reference." }, "version": { "type": [ "string", "null" ], "description": "An optional specific version to use." } } }, "Status": { "type": "string", "enum": [ "completed", "failed", "in_progress", "cancelled", "queued", "incomplete" ] }, "StopConfiguration": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "SummaryPart": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SummaryTextContent" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "summary_text" ] } } } ] } ] }, "SummaryTextContent": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "A summary of the reasoning output from the model so far." } } }, "TenantListItem": { "type": "object", "required": [ "client_id", "name", "status", "is_active", "logged_in" ], "properties": { "client_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AppStatus" }, "is_active": { "type": "boolean" }, "logged_in": { "type": "boolean" } } }, "TenantListResponse": { "type": "object", "required": [ "tenants" ], "properties": { "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/TenantListItem" } } } }, "TestCreds": { "oneOf": [ { "type": "object", "description": "Look up credentials from stored API model", "required": [ "value", "type" ], "properties": { "value": { "type": "string", "description": "Look up credentials from stored API model" }, "type": { "type": "string", "enum": [ "id" ] } }, "example": { "type": "id", "value": "openai-gpt4" } }, { "type": "object", "description": "Use direct API key (null for no authentication)", "required": [ "value", "type" ], "properties": { "value": { "$ref": "#/components/schemas/ApiKey", "description": "Use direct API key (null for no authentication)" }, "type": { "type": "string", "enum": [ "api_key" ] } }, "example": { "type": "api_key", "value": "sk-1234567890abcdef" } } ], "description": "Credentials for test/fetch operations" }, "TestPromptRequest": { "type": "object", "description": "Request to test API connectivity with a prompt", "required": [ "base_url", "model", "prompt" ], "properties": { "creds": { "$ref": "#/components/schemas/TestCreds", "description": "Credentials to use for testing" }, "base_url": { "type": "string", "description": "API base URL" }, "model": { "type": "string", "description": "Model to use for testing" }, "prompt": { "type": "string", "description": "Test prompt (max 30 characters for cost control)" }, "api_format": { "$ref": "#/components/schemas/ApiFormat", "description": "API format to use for the test request (defaults to OpenAI Chat Completions)" } }, "example": { "base_url": "https://api.openai.com/v1", "creds": { "type": "api_key", "value": "sk-..." }, "model": "gpt-4", "prompt": "Hello, how are you?" } }, "TestPromptResponse": { "type": "object", "description": "Response from testing API connectivity", "required": [ "success" ], "properties": { "success": { "type": "boolean" }, "response": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "example": { "error": null, "response": "Hello! I'm doing well, thank you.", "success": true } }, "TextResponseFormatConfiguration": { "oneOf": [ { "type": "object", "description": "Default response format. Used to generate text responses.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "description": "JSON object response format. An older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it.\nNote that the model will not generate JSON without a system or user message\ninstructing it to do so.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "json_object" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/ResponseFormatJsonSchema", "description": "JSON Schema response format. Used to generate structured JSON responses.\nLearn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "json_schema" ] } } } ], "description": "JSON Schema response format. Used to generate structured JSON responses.\nLearn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)." } ] }, "TokenCreated": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "API token with bodhiapp_ prefix for programmatic access", "example": "bodhiapp_1234567890abcdef" } }, "example": { "token": "bodhiapp_1234567890abcdef" } }, "TokenDetail": { "type": "object", "required": [ "id", "user_id", "name", "token_prefix", "scopes", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "type": "string" }, "token_prefix": { "type": "string" }, "scopes": { "type": "string" }, "status": { "$ref": "#/components/schemas/TokenStatus" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TokenInfo": { "type": "object", "description": "API Token information response", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/TokenScope" } } }, "TokenScope": { "type": "string", "enum": [ "scope_token_user", "scope_token_power_user" ] }, "TokenStatus": { "type": "string", "enum": [ "active", "inactive" ] }, "Tool": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionTool", "description": "Defines a function in your own code the model can choose to call. Learn more about [function\ncalling](https://platform.openai.com/docs/guides/tools)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ], "description": "Defines a function in your own code the model can choose to call. Learn more about [function\ncalling](https://platform.openai.com/docs/guides/tools)." }, { "allOf": [ { "$ref": "#/components/schemas/FileSearchTool", "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search\ntool](https://platform.openai.com/docs/guides/tools-file-search)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_search" ] } } } ], "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search\ntool](https://platform.openai.com/docs/guides/tools-file-search)." }, { "allOf": [ { "$ref": "#/components/schemas/ComputerUsePreviewTool", "description": "A tool that controls a virtual computer. Learn more about the [computer\nuse tool](https://platform.openai.com/docs/guides/tools-computer-use)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ] } } } ], "description": "A tool that controls a virtual computer. Learn more about the [computer\nuse tool](https://platform.openai.com/docs/guides/tools-computer-use)." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool", "description": "Search the Internet for sources related to the prompt. Learn more about the\n[web search tool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search" ] } } } ], "description": "Search the Internet for sources related to the prompt. Learn more about the\n[web search tool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool", "description": "type: web_search_2025_08_26" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_2025_08_26" ] } } } ], "description": "type: web_search_2025_08_26" }, { "allOf": [ { "$ref": "#/components/schemas/MCPTool", "description": "Give the model access to additional tools via remote Model Context Protocol\n(MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp" ] } } } ], "description": "Give the model access to additional tools via remote Model Context Protocol\n(MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp)." }, { "allOf": [ { "$ref": "#/components/schemas/CodeInterpreterTool", "description": "A tool that runs Python code to help generate a response to a prompt." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "code_interpreter" ] } } } ], "description": "A tool that runs Python code to help generate a response to a prompt." }, { "allOf": [ { "$ref": "#/components/schemas/ImageGenTool", "description": "A tool that generates images using a model like `gpt-image-1`." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_generation" ] } } } ], "description": "A tool that generates images using a model like `gpt-image-1`." }, { "type": "object", "description": "A tool that allows the model to execute shell commands in a local environment.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "local_shell" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/FunctionShellToolParam", "description": "A tool that allows the model to execute shell commands." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell" ] } } } ], "description": "A tool that allows the model to execute shell commands." }, { "allOf": [ { "$ref": "#/components/schemas/CustomToolParam", "description": "A custom tool that processes input using a specified format. Learn more about [custom\ntools](https://platform.openai.com/docs/guides/function-calling#custom-tools)" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ], "description": "A custom tool that processes input using a specified format. Learn more about [custom\ntools](https://platform.openai.com/docs/guides/function-calling#custom-tools)" }, { "allOf": [ { "$ref": "#/components/schemas/ComputerTool", "description": "A tool that controls a virtual computer. Learn more about the\n[computer tool](https://platform.openai.com/docs/guides/tools-computer-use)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer" ] } } } ], "description": "A tool that controls a virtual computer. Learn more about the\n[computer tool](https://platform.openai.com/docs/guides/tools-computer-use)." }, { "allOf": [ { "$ref": "#/components/schemas/NamespaceToolParam", "description": "Groups function/custom tools under a shared namespace." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "namespace" ] } } } ], "description": "Groups function/custom tools under a shared namespace." }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchToolParam", "description": "Hosted or BYOT tool search configuration for deferred tools." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool_search" ] } } } ], "description": "Hosted or BYOT tool search configuration for deferred tools." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool", "description": " This tool searches the web for relevant results to use in a response. Learn more about the [web search\ntool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_preview" ] } } } ], "description": " This tool searches the web for relevant results to use in a response. Learn more about the [web search\ntool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchTool", "description": "type: web_search_preview_2025_03_11" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_preview_2025_03_11" ] } } } ], "description": "type: web_search_preview_2025_03_11" }, { "type": "object", "description": "Allows the assistant to create, delete, or update files using unified diffs.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch" ] } } } ], "description": "Definitions for model-callable tools." }, "ToolCapabilities": { "type": "object", "properties": { "function_calling": { "type": [ "boolean", "null" ] }, "structured_output": { "type": [ "boolean", "null" ] } } }, "ToolChoiceAllowed": { "type": "object", "required": [ "mode", "tools" ], "properties": { "mode": { "$ref": "#/components/schemas/ToolChoiceAllowedMode", "description": "Constrains the tools available to the model to a pre-defined set.\n\n`auto` allows the model to pick from among the allowed tools and generate a\nmessage.\n\n`required` requires the model to call one or more of the allowed tools." }, "tools": { "type": "array", "items": { "type": "object" }, "description": "A list of tool definitions that the model should be allowed to call.\n\nFor the Responses API, the list of tool definitions might look like:\n```json\n[\n { \"type\": \"function\", \"name\": \"get_weather\" },\n { \"type\": \"mcp\", \"server_label\": \"deepwiki\" },\n { \"type\": \"image_generation\" }\n]\n```" } } }, "ToolChoiceAllowedMode": { "type": "string", "enum": [ "auto", "required" ] }, "ToolChoiceCustom": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the custom tool to call." } } }, "ToolChoiceFunction": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the function to call." } } }, "ToolChoiceMCP": { "type": "object", "required": [ "name", "server_label" ], "properties": { "name": { "type": "string", "description": "The name of the tool to call on the server." }, "server_label": { "type": "string", "description": "The label of the MCP server to use." } } }, "ToolChoiceOptions": { "type": "string", "enum": [ "none", "auto", "required" ] }, "ToolChoiceParam": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceAllowed", "description": "Constrains the tools available to the model to a pre-defined set." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] } } } ], "description": "Constrains the tools available to the model to a pre-defined set." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceFunction", "description": "Use this option to force the model to call a specific function." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "function" ] } } } ], "description": "Use this option to force the model to call a specific function." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceMCP", "description": "Use this option to force the model to call a specific tool on a remote MCP server." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mcp" ] } } } ], "description": "Use this option to force the model to call a specific tool on a remote MCP server." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceCustom", "description": "Use this option to force the model to call a custom tool." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] } } } ], "description": "Use this option to force the model to call a custom tool." }, { "type": "object", "description": "Forces the model to call the apply_patch tool when executing a tool call.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "apply_patch" ] } } }, { "type": "object", "description": "Forces the model to call the function shell tool when a tool call is required.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "shell" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceTypes", "description": "Indicates that the model should use a built-in tool to generate a response.\n[Learn more about built-in tools](https://platform.openai.com/docs/guides/tools)." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "hosted" ] } } } ], "description": "Indicates that the model should use a built-in tool to generate a response.\n[Learn more about built-in tools](https://platform.openai.com/docs/guides/tools)." }, { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceOptions", "description": "Controls which (if any) tool is called by the model.\n\n`none` means the model will not call any tool and instead generates a message.\n\n`auto` means the model can pick between generating a message or calling one or\nmore tools.\n\n`required` means the model must call one or more tools." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "mode" ] } } } ], "description": "Controls which (if any) tool is called by the model.\n\n`none` means the model will not call any tool and instead generates a message.\n\n`auto` means the model can pick between generating a message or calling one or\nmore tools.\n\n`required` means the model must call one or more tools." } ] }, "ToolChoiceTypes": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "file_search" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_preview" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "computer_use" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "web_search_preview_2025_03_11" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "code_interpreter" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_generation" ] } } } ], "description": "The type of hosted tool the model should to use. Learn more about\n[built-in tools](https://platform.openai.com/docs/guides/tools)." }, "ToolSearchCall": { "type": "object", "description": "A tool search call output item.", "required": [ "id", "execution", "arguments", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the tool search call item." }, "call_id": { "type": [ "string", "null" ], "description": "The unique ID of the tool search call generated by the model." }, "execution": { "$ref": "#/components/schemas/ToolSearchExecutionType", "description": "Whether tool search was executed by the server or by the client." }, "arguments": { "type": "object", "description": "Arguments used for the tool search call." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus", "description": "The status of the tool search call item." }, "created_by": { "type": [ "string", "null" ], "description": "The identifier of the actor that created the item." } } }, "ToolSearchCallItemParam": { "type": "object", "description": "A tool search call input item.", "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of this tool search call." }, "call_id": { "type": [ "string", "null" ], "description": "The unique ID of the tool search call generated by the model." }, "execution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolSearchExecutionType", "description": "Whether tool search was executed by the server or by the client." } ] }, "arguments": { "type": "object", "description": "The arguments supplied to the tool search call." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the tool search call." } ] } } }, "ToolSearchExecutionType": { "type": "string", "description": "Whether tool search was executed by the server or by the client.", "enum": [ "server", "client" ] }, "ToolSearchOutput": { "type": "object", "description": "A tool search output item.", "required": [ "id", "execution", "tools", "status" ], "properties": { "id": { "type": "string", "description": "The unique ID of the tool search output item." }, "call_id": { "type": [ "string", "null" ], "description": "The unique ID of the tool search call generated by the model." }, "execution": { "$ref": "#/components/schemas/ToolSearchExecutionType", "description": "Whether tool search was executed by the server or by the client." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" }, "description": "The loaded tool definitions returned by tool search." }, "status": { "$ref": "#/components/schemas/FunctionCallOutputStatusEnum", "description": "The status of the tool search output item." }, "created_by": { "type": [ "string", "null" ], "description": "The identifier of the actor that created the item." } } }, "ToolSearchOutputItemParam": { "type": "object", "description": "A tool search output input item.", "required": [ "tools" ], "properties": { "id": { "type": [ "string", "null" ], "description": "The unique ID of this tool search output." }, "call_id": { "type": [ "string", "null" ], "description": "The unique ID of the tool search call generated by the model." }, "execution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolSearchExecutionType", "description": "Whether tool search was executed by the server or by the client." } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" }, "description": "The loaded tool definitions returned by the tool search output." }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OutputStatus", "description": "The status of the tool search output." } ] } } }, "ToolSearchToolParam": { "type": "object", "description": "Hosted or BYOT tool search configuration for deferred tools.", "properties": { "execution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ToolSearchExecutionType", "description": "Whether tool search is executed by the server or by the client." } ] }, "description": { "type": [ "string", "null" ], "description": "Description shown to the model for a client-executed tool search tool." }, "parameters": { "type": [ "object", "null" ], "description": "Parameter schema for a client-executed tool search tool." } } }, "TopLogProb": { "type": "object", "required": [ "bytes", "logprob", "token" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "logprob": { "type": "number", "format": "double" }, "token": { "type": "string" } } }, "TopLogprobs": { "type": "object", "required": [ "token", "logprob" ], "properties": { "token": { "type": "string", "description": "The token." }, "logprob": { "type": "number", "format": "float", "description": "The log probability of this token." }, "bytes": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token." } } }, "Truncation": { "type": "string", "description": "Truncation strategies.", "enum": [ "auto", "disabled" ] }, "TypeParam": { "type": "object", "description": "A typing (text entry) action.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The text to type." } } }, "UpdateSettingRequest": { "type": "object", "description": "Request to update a setting value", "required": [ "value" ], "properties": { "value": { "description": "New value for the setting (type depends on setting metadata)" } }, "example": { "value": "debug" } }, "UpdateTokenRequest": { "type": "object", "required": [ "name", "status" ], "properties": { "name": { "type": "string", "description": "New descriptive name for the token", "example": "Updated Token Name", "maxLength": 100, "minLength": 3 }, "status": { "$ref": "#/components/schemas/TokenStatus", "description": "New status for the token (active/inactive)" } }, "example": { "name": "Updated Token Name", "status": "inactive" } }, "UrlCitation": { "type": "object", "required": [ "end_index", "start_index", "title", "url" ], "properties": { "end_index": { "type": "integer", "format": "int32", "description": "The index of the last character of the URL citation in the message.", "minimum": 0 }, "start_index": { "type": "integer", "format": "int32", "description": "The index of the first character of the URL citation in the message.", "minimum": 0 }, "title": { "type": "string", "description": "The title of the web resource." }, "url": { "type": "string", "description": "The URL of the web resource." } } }, "UrlCitationBody": { "type": "object", "required": [ "end_index", "start_index", "title", "url" ], "properties": { "end_index": { "type": "integer", "format": "int32", "description": "The index of the last character of the URL citation in the message.", "minimum": 0 }, "start_index": { "type": "integer", "format": "int32", "description": "The index of the first character of the URL citation in the message.", "minimum": 0 }, "title": { "type": "string", "description": "The title of the web resource." }, "url": { "type": "string", "description": "The URL of the web resource." } } }, "UserAccessRequest": { "type": "object", "description": "User access request output type for API responses", "required": [ "id", "username", "user_id", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "user_id": { "type": "string" }, "reviewer": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/UserAccessRequestStatus" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UserAccessRequestStatus": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "UserAccessStatusResponse": { "type": "object", "description": "Response for checking access request status", "required": [ "username", "status", "created_at", "updated_at" ], "properties": { "username": { "type": "string", "description": "Username of the requesting user" }, "status": { "$ref": "#/components/schemas/UserAccessRequestStatus", "description": "Current status of the request (pending, approved, rejected)" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "example": { "created_at": "2024-01-01T12:00:00Z", "status": "pending", "updated_at": "2024-01-01T12:00:00Z", "username": "user@example.com" } }, "UserAlias": { "type": "object", "required": [ "id", "alias", "repo", "filename", "snapshot", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "alias": { "type": "string" }, "repo": { "type": "string", "format": "string" }, "filename": { "type": "string" }, "snapshot": { "type": "string" }, "request_params": { "$ref": "#/components/schemas/OAIRequestParams" }, "context_params": { "$ref": "#/components/schemas/JsonVec" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UserAliasRequest": { "type": "object", "description": "Input request for creating or updating a user model alias.", "required": [ "alias", "repo", "filename" ], "properties": { "alias": { "type": "string", "description": "Alias name — unique per (tenant_id, user_id) scope" }, "repo": { "type": "string", "description": "Repository in format \"user/repo\"" }, "filename": { "type": "string", "description": "Filename of the GGUF model" }, "snapshot": { "type": [ "string", "null" ], "description": "Snapshot/commit identifier (optional — defaults to latest available)" }, "request_params": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAIRequestParams", "description": "Request parameters for the model" } ] }, "context_params": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Context parameters for the model" } }, "example": { "alias": "llama3:instruct", "context_params": [ "--ctx-size 4096" ], "filename": "Meta-Llama-3-8B-Instruct.Q4_K_M.gguf", "repo": "QuantFactory/Meta-Llama-3-8B-Instruct-GGUF", "request_params": { "temperature": 0.7 } } }, "UserAliasResponse": { "type": "object", "description": "User-defined model alias response", "required": [ "id", "alias", "repo", "filename", "snapshot", "source", "model_params", "request_params", "context_params", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "alias": { "type": "string" }, "repo": { "type": "string" }, "filename": { "type": "string" }, "snapshot": { "type": "string" }, "source": { "type": "string" }, "model_params": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "request_params": { "$ref": "#/components/schemas/OAIRequestParams" }, "context_params": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModelMetadata", "description": "Model metadata extracted from GGUF file (optional)" } ] } } }, "UserInfo": { "type": "object", "required": [ "user_id", "username" ], "properties": { "user_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "username": { "type": "string", "example": "user@example.com" }, "first_name": { "type": [ "string", "null" ], "example": "John" }, "last_name": { "type": [ "string", "null" ], "example": "Doe" }, "role": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AppRole" } ] } } }, "UserInfoEnvelope": { "allOf": [ { "$ref": "#/components/schemas/UserResponse", "description": "Core user authentication response" }, { "type": "object", "properties": { "dashboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DashboardUser", "description": "Dashboard user info when a validated dashboard session exists" } ] } } } ], "description": "Envelope wrapping UserResponse with additional session info" }, "UserListResponse": { "type": "object", "required": [ "client_id", "users", "page", "page_size", "total_pages", "total_users", "has_next", "has_previous" ], "properties": { "client_id": { "type": "string", "example": "resource-abc123def456" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" } }, "page": { "type": "integer", "format": "int32", "example": 1, "minimum": 0 }, "page_size": { "type": "integer", "format": "int32", "example": 10, "minimum": 0 }, "total_pages": { "type": "integer", "format": "int32", "example": 5, "minimum": 0 }, "total_users": { "type": "integer", "format": "int32", "example": 45, "minimum": 0 }, "has_next": { "type": "boolean", "example": true }, "has_previous": { "type": "boolean", "example": false } } }, "UserResponse": { "oneOf": [ { "type": "object", "description": "User is not authenticated", "required": [ "auth_status" ], "properties": { "auth_status": { "type": "string", "enum": [ "logged_out" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/UserInfo", "description": "User is authenticated with details" }, { "type": "object", "required": [ "auth_status" ], "properties": { "auth_status": { "type": "string", "enum": [ "logged_in" ] } } } ], "description": "User is authenticated with details" }, { "allOf": [ { "$ref": "#/components/schemas/TokenInfo", "description": "API token authentication" }, { "type": "object", "required": [ "auth_status" ], "properties": { "auth_status": { "type": "string", "enum": [ "api_token" ] } } } ], "description": "API token authentication" } ], "description": "User authentication response with discriminated union", "example": { "auth_status": "logged_in", "role": "resource_user", "user_id": "550e8400-e29b-41d4-a716-446655440000", "username": "user@example.com" } }, "UserScope": { "type": "string", "enum": [ "scope_user_user", "scope_user_power_user" ] }, "Verbosity": { "type": "string", "description": "o-series reasoning settings.", "enum": [ "low", "medium", "high" ] }, "WebSearchActionFind": { "type": "object", "required": [ "url", "pattern" ], "properties": { "url": { "type": "string", "description": "The URL of the page searched for the pattern." }, "pattern": { "type": "string", "description": "The pattern or text to search for within the page." } } }, "WebSearchActionOpenPage": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "description": "The URL opened by the model." } } }, "WebSearchActionSearch": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The search query." }, "sources": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebSearchActionSearchSource" }, "description": "The sources used in the search." } } }, "WebSearchActionSearchSource": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "description": "The type of source. Always `url`." }, "url": { "type": "string", "description": "The URL of the source." } } }, "WebSearchApproximateLocation": { "type": "object", "description": "Approximate user location for web search.", "properties": { "type": { "$ref": "#/components/schemas/WebSearchApproximateLocationType", "description": "The type of location approximation. Defaults to `approximate` when omitted in JSON input." }, "city": { "type": [ "string", "null" ], "description": "Free text input for the city of the user, e.g. `San Francisco`." }, "country": { "type": [ "string", "null" ], "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user,\ne.g. `US`." }, "region": { "type": [ "string", "null" ], "description": "Free text input for the region of the user, e.g. `California`." }, "timezone": { "type": [ "string", "null" ], "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g.\n`America/Los_Angeles`." } } }, "WebSearchApproximateLocationType": { "type": "string", "enum": [ "approximate" ] }, "WebSearchContextSize": { "type": "string", "description": "The amount of context window space to use for the search.", "enum": [ "low", "medium", "high" ] }, "WebSearchLocation": { "type": "object", "description": "Approximate location parameters for the search.", "properties": { "country": { "type": [ "string", "null" ], "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, "region": { "type": [ "string", "null" ], "description": "Free text input for the region of the user, e.g. `California`." }, "city": { "type": [ "string", "null" ], "description": "Free text input for the city of the user, e.g. `San Francisco`." }, "timezone": { "type": [ "string", "null" ], "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." } } }, "WebSearchOptions": { "type": "object", "description": "Options for the web search tool.", "properties": { "search_context_size": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchContextSize", "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } ] }, "user_location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchUserLocation", "description": "Approximate location parameters for the search." } ] } } }, "WebSearchTool": { "type": "object", "properties": { "filters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchToolFilters", "description": "Filters for the search." } ] }, "user_location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchApproximateLocation", "description": "The approximate location of the user." } ] }, "search_context_size": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebSearchToolSearchContextSize", "description": "High level guidance for the amount of context window space to use for the search. One of `low`,\n`medium`, or `high`. `medium` is the default." } ] }, "search_content_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SearchContentType" }, "description": "The types of content to search for." } } }, "WebSearchToolCall": { "type": "object", "description": "Web search tool call output.", "required": [ "action", "id", "status" ], "properties": { "action": { "$ref": "#/components/schemas/WebSearchToolCallAction", "description": "An object describing the specific action taken in this web search call. Includes\ndetails on how the model used the web (search, open_page, find, find_in_page)." }, "id": { "type": "string", "description": "The unique ID of the web search tool call." }, "status": { "$ref": "#/components/schemas/WebSearchToolCallStatus", "description": "The status of the web search tool call." } } }, "WebSearchToolCallAction": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/WebSearchActionSearch", "description": "Action type \"search\" - Performs a web search query." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "search" ] } } } ], "description": "Action type \"search\" - Performs a web search query." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchActionOpenPage", "description": "Action type \"open_page\" - Opens a specific URL from search results." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "open_page" ] } } } ], "description": "Action type \"open_page\" - Opens a specific URL from search results." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchActionFind", "description": "Action type \"find\": Searches for a pattern within a loaded page." }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "find" ] } } } ], "description": "Action type \"find\": Searches for a pattern within a loaded page." }, { "allOf": [ { "$ref": "#/components/schemas/WebSearchActionFind", "description": "Action type \"find_in_page\": https://platform.openai.com/docs/guides/tools-web-search#output-and-citations" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "find_in_page" ] } } } ], "description": "Action type \"find_in_page\": https://platform.openai.com/docs/guides/tools-web-search#output-and-citations" } ] }, "WebSearchToolCallStatus": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed" ] }, "WebSearchToolFilters": { "type": "object", "properties": { "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Allowed domains for the search. If not provided, all domains are allowed.\nSubdomains of the provided domains are allowed as well.\n\nExample: `[\"pubmed.ncbi.nlm.nih.gov\"]`" } } }, "WebSearchToolSearchContextSize": { "type": "string", "enum": [ "low", "medium", "high" ] }, "WebSearchUserLocation": { "type": "object", "required": [ "type", "approximate" ], "properties": { "type": { "$ref": "#/components/schemas/WebSearchUserLocationType" }, "approximate": { "$ref": "#/components/schemas/WebSearchLocation" } } }, "WebSearchUserLocationType": { "type": "string", "enum": [ "approximate" ] } }, "securitySchemes": { "bearer_api_token": { "type": "http", "scheme": "bearer", "bearerFormat": "bodhiapp_", "description": "API token authentication. Create tokens via web interface at Menu > Settings > API Tokens. Format: 'bodhiapp_'. Use as: Authorization: Bearer \n\nScopes:\n- scope_token_user: Basic API access - read operations\n- scope_token_power_user: Advanced operations - create/update models, downloads\n- scope_token_manager: User management operations\n- scope_token_admin: Full administrative access" }, "bearer_oauth_token": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.1 token exchange authentication. External OAuth providers can exchange tokens with UserScope claims for access to Bodhi resources. Use as: Authorization: Bearer \n\nScopes:\n- scope_user_user: Basic user access via OAuth 2.1 token exchange\n- scope_user_power_user: Advanced user operations via OAuth 2.1 token exchange\n- scope_user_manager: Manager operations via OAuth 2.1 token exchange\n- scope_user_admin: Admin operations via OAuth 2.1 token exchange" }, "session_auth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "/bodhi/v1/auth/initiate", "tokenUrl": "/bodhi/v1/auth/callback", "scopes": { "resource_admin": "Admin operations via browser session (session-only)", "resource_manager": "Manager operations via browser session (session-only)", "resource_power_user": "Power user operations via browser session", "resource_user": "Basic authenticated user access via browser session" } } }, "description": "Browser session authentication. Login via /bodhi/v1/auth/initiate. Some operations (token management, settings, user management) require session authentication only." } } }, "tags": [ { "name": "system", "description": "System information and operations" }, { "name": "setup", "description": "Application setup and initialization" }, { "name": "auth", "description": "Authentication and session management" }, { "name": "api-keys", "description": "API keys management" }, { "name": "models", "description": "Model files and aliases" }, { "name": "models-alias", "description": "User-created model aliases" }, { "name": "models-api", "description": "Remote AI API model configuration" }, { "name": "models-files", "description": "Local model files and downloads" }, { "name": "settings", "description": "Application settings management" }, { "name": "mcps", "description": "MCP server management and tool execution" }, { "name": "openai", "description": "OpenAI-compatible API endpoints" }, { "name": "responses", "description": "OpenAI Responses API proxy endpoints" }, { "name": "ollama", "description": "Ollama-compatible API endpoints" }, { "name": "apps", "description": "External app API endpoints (OAuth token required)" }, { "name": "tenants", "description": "Tenant management endpoints" } ], "externalDocs": { "url": "https://getbodhi.app/docs/api", "description": "Find more info here" } }