{ "openapi": "3.1.0", "info": { "title": "Mixpeek API", "description": "This is the Mixpeek API, providing access to various endpoints for data processing and retrieval.", "termsOfService": "https://mixpeek.com/terms", "contact": { "name": "Mixpeek Support", "url": "https://mixpeek.com/contact", "email": "info@mixpeek.com" }, "version": "0.82" }, "servers": [ { "url": "https://api.mixpeek.com", "description": "Production" } ], "paths": { "/v1/public/retrievers/": { "get": { "tags": [ "Public Retriever API" ], "summary": "List Public Retrievers", "description": "List all public retrievers with pagination and search.\n\nThis endpoint allows browsing and discovering all published retrievers\nacross all organizations. No authentication required.\n\n**Authentication:**\n- NO authentication required - completely public endpoint\n- Discover retrievers created by all Mixpeek users\n\n**Pagination:**\n- Default: page=1, page_size=20\n- Maximum page_size: 100\n- Returns total count and total pages\n\n**Search:**\n- Search across retriever titles and descriptions\n- Case-insensitive regex matching\n- Combine with pagination\n\n**Filtering:**\n- By default, only active retrievers are shown\n- Set `include_inactive=true` to see all retrievers\n\n**Response includes:**\n- List of public retrievers with basic info\n- Pagination details (page, page_size, total_count, total_pages)\n- Aggregate statistics (total active, password protected, open)\n\n**What's NOT exposed:**\n- API keys (except in individual config endpoint)\n- Internal IDs or organization details\n- Full retriever configuration (use template endpoint for that)\n- Password values (only password_protected: true/false)\n\n**Example:**\n```bash\n# List all public retrievers (first page)\ncurl -X GET \"https://api.mixpeek.com/v1/public/retrievers/\"\n\n# Search for video-related retrievers\ncurl -X GET \"https://api.mixpeek.com/v1/public/retrievers/?search=video&page_size=50\"\n\n# Get page 2 with custom page size\ncurl -X GET \"https://api.mixpeek.com/v1/public/retrievers/?page=2&page_size=50\"\n```\n\n**Use Cases:**\n- Browse available public retrievers\n- Discover search patterns and implementations\n- Find retrievers to use as templates\n- Explore what others have built", "operationId": "list_public_retrievers_v1_public_retrievers__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Results per page", "default": 20, "title": "Page Size" }, "description": "Results per page" }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include inactive retrievers in results", "default": false, "title": "Include Inactive" }, "description": "Include inactive retrievers in results" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Search query for filtering by title or description", "title": "Search" }, "description": "Search query for filtering by title or description" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicRetrieversResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/execute": { "post": { "tags": [ "Public Retriever API" ], "summary": "Execute Public Retriever", "description": "Execute a published retriever (public endpoint).\n\n**Authentication:**\n- API key is OPTIONAL for public retrievers\n- Supports: no key, prk_ keys (deprecated), or ret_sk_ keys\n- If password-protected, requires `X-Retriever-Password` header\n\n**Rate Limiting:**\n- Subject to per-retriever rate limits (per minute/hour/day)\n- May also have IP-based rate limits\n\n**Response:**\n- Only returns fields specified in `exposed_fields` configuration\n- Internal metadata is stripped from results\n- Includes `execution_id` for interaction tracking\n- Presigned URLs returned by default (return_presigned_urls=true) for media rendering\n\n**Example (no API key - recommended for public access):**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/public/retrievers/video-search/execute\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"inputs\": {\"query\": \"red car\"},\n \"pagination\": {\"method\": \"offset\", \"page_number\": 1, \"page_size\": 10}\n }'\n```\n\n**Example with ret_sk_ key (for SDK/programmatic access):**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/public/retrievers/video-search/execute\" \\\n -H \"X-Public-API-Key: ret_sk_abc123...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"inputs\": {\"query\": \"red car\"},\n \"pagination\": {\"method\": \"offset\", \"page_number\": 1, \"page_size\": 10}\n }'\n```", "operationId": "execute_public_retriever_v1_public_retrievers__public_name__execute_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage. Default: True for public retrievers to enable media rendering. Set to False if you only need metadata without URLs.", "default": true, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage. Default: True for public retrievers to enable media rendering. Set to False if you only need metadata without URLs." }, { "name": "X-Public-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Public-Api-Key" } }, { "name": "X-Retriever-Password", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Retriever-Password" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverExecutionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/config": { "get": { "tags": [ "Public Retriever API" ], "summary": "Get Public Retriever Config", "description": "Get display configuration for public page rendering.\n\n\u26a0\ufe0f **DEPRECATED**: Use `/v1/marketplace/catalog/{public_name}/config` instead.\nThis endpoint is maintained for backwards compatibility but may be removed in the future.\n\nReturns the UI configuration needed to render the public search interface.\nUsed by the frontend app at mxp.co to dynamically build the UI.\n\n**Authentication:**\n- NO authentication required - this endpoint is public\n- Anyone can access the config if they know the public_name\n- The config includes the public_api_key needed for execute/interact endpoints\n\n**Response includes:**\n- Display config (logo, theme, components, field rendering)\n- Title and description\n- Password protection status\n- Public API key for subsequent authenticated requests\n\n**Example (deprecated):**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/public/retrievers/video-search/config\"\n```\n\n**Example (recommended):**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/marketplace/catalog/video-search/config\"\n```", "operationId": "get_public_retriever_config_v1_public_retrievers__public_name__config_get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRetrieverConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/verify": { "post": { "tags": [ "Public Retriever API" ], "summary": "Verify Password", "description": "Verify password for a password-protected retriever.\n\nAllows the frontend to check if a password is valid before attempting to execute\na password-protected retriever. Returns the public API key if the password is valid.\n\n**Authentication:**\n- NO authentication required - this endpoint is public\n- The password is verified against the retriever's configured password\n\n**Use Case:**\n1. Frontend detects that a retriever is password-protected (from /config endpoint)\n2. User enters password in the UI\n3. Frontend calls this endpoint to verify the password\n4. If valid, frontend receives the public_api_key to use for subsequent requests\n\n**Response:**\n- `valid`: Whether the password is correct\n- `public_api_key`: The API key to use for execute/interact endpoints (only if valid)\n\n**Example:**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/public/retrievers/private-search/verify\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"password\": \"secret123\"}'\n```\n\n**Response if valid:**\n```json\n{\n \"valid\": true,\n \"public_api_key\": \"prk_abc123...\"\n}\n```\n\n**Response if invalid:**\n```json\n{\n \"valid\": false,\n \"public_api_key\": null\n}\n```", "operationId": "verify_password_v1_public_retrievers__public_name__verify_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPasswordRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPasswordResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/interactions": { "post": { "tags": [ "Public Retriever API" ], "summary": "Track Interaction", "description": "Track user interaction with search results.\n\nRecords user engagement (clicks, views, etc.) for analytics and\npotential search optimization (Learning to Rank).\n\n**Authentication:**\n- API key is OPTIONAL (same as execute endpoint)\n- Password NOT required (tracking should work even without auth)\n\n**Recommended Headers:**\n- `X-Session-ID`: Session identifier for tracking user journey\n\n**Interaction Types:**\n- `VIEW`: Result was visible in viewport\n- `CLICK`: User clicked on result\n- `POSITIVE_FEEDBACK`: User explicitly liked result\n- `NEGATIVE_FEEDBACK`: User explicitly disliked result\n- `PURCHASE`: User purchased/converted\n- `ADD_TO_CART`: User added to cart\n- `WISHLIST`: User added to wishlist\n- `LONG_VIEW`: User spent significant time viewing\n- `SHARE`: User shared result\n- `BOOKMARK`: User bookmarked result\n\n**Example:**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/public/retrievers/video-search/interactions\" \\\n -H \"X-Session-ID: sess_xyz...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document_id\": \"doc_123\",\n \"interaction_type\": [\"CLICK\"],\n \"position\": 2,\n \"execution_id\": \"exec_abc\",\n \"query_snapshot\": {\"query\": \"red car\"}\n }'\n```", "operationId": "track_interaction_v1_public_retrievers__public_name__interactions_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" }, { "name": "X-Session-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Session-Id" } }, { "name": "X-Public-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Public-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInteractionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/interactions/batch": { "post": { "tags": [ "Public Retriever API" ], "summary": "Track Interaction Batch", "description": "Track multiple interactions in a single request (batching).\n\nMore efficient than sending individual interaction requests.\nUse this for batching viewport visibility, bulk actions, etc.\n\n**Authentication:**\n- API key is OPTIONAL (same as execute endpoint)\n- Password NOT required (tracking should work even without auth)\n\n**Recommended Headers:**\n- `X-Session-ID`: Applied to all interactions in the batch\n\n**Limits:**\n- Maximum 100 interactions per batch\n\n**Example:**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/public/retrievers/video-search/interactions/batch\" \\\n -H \"X-Session-ID: sess_xyz...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"interactions\": [\n {\n \"document_id\": \"doc_123\",\n \"interaction_type\": [\"VIEW\"],\n \"position\": 0,\n \"execution_id\": \"exec_abc\"\n },\n {\n \"document_id\": \"doc_456\",\n \"interaction_type\": [\"VIEW\"],\n \"position\": 1,\n \"execution_id\": \"exec_abc\"\n }\n ]\n }'\n```", "operationId": "track_interaction_batch_v1_public_retrievers__public_name__interactions_batch_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" }, { "name": "X-Session-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Session-Id" } }, { "name": "X-Public-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Public-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInteractionBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/retrievers/{public_name}/template": { "get": { "tags": [ "Public Retriever API" ], "summary": "Get Public Retriever Template", "description": "Get retriever configuration as a reusable template.\n\nReturns the published retriever's configuration in a format that can be\ndirectly used to create your own retriever. This is perfect for discovering\npatterns and adapting them to your own data.\n\n**Authentication:**\n- NO authentication required - this endpoint is completely public\n- Anyone can get the template if they know the public_name\n\n**Use Case:**\n1. Browse public retrievers to find patterns you like\n2. GET this endpoint to get the full configuration\n3. Copy the config and modify for your needs (especially `collection_identifiers`)\n4. POST to `/v1/retrievers` to create your own retriever\n5. Optionally publish it with the same display_config\n\n**What's included:**\n- Retriever configuration (stages, input_schema, budget_limits)\n- Display configuration (for publishing with similar UI)\n- Original metadata for reference\n\n**What you need to change:**\n- `collection_identifiers`: Replace with your own collection IDs\n- `retriever_name`: Give it a unique name\n- Optionally modify stages, inputs, display_config as needed\n\n**Example:**\n```bash\n# 1. Get the template\ncurl -X GET \"https://api.mixpeek.com/v1/public/retrievers/video-search/template\"\n\n# 2. Modify the response and create your own retriever\ncurl -X POST \"https://api.mixpeek.com/v1/retrievers\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"retriever_name\": \"my_video_search\",\n \"collection_identifiers\": [\"my_videos\"],\n \"stages\": [...], # From template\n \"input_schema\": {...}, # From template\n \"budget_limits\": {...}, # From template\n \"display_config\": {...} # From template (optional)\n }'\n```\n\n**Response includes:**\n- All retriever configuration fields\n- Display config for publishing (optional to use)\n- Source reference (where this template came from)", "operationId": "get_public_retriever_template_v1_public_retrievers__public_name__template_get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the published retriever", "title": "Public Name" }, "description": "Public name of the published retriever" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRetrieverTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/scaffolds": { "get": { "tags": [ "Public Templates API", "Public Scaffolds" ], "summary": "List Scaffolds", "description": "List available scaffold templates (public, no auth required).\n\nScaffolds are pre-configured templates that create complete infrastructure:\n- Namespace with feature extractors\n- Bucket with data schema\n- Collection with processing config\n- Retriever with search pipeline\n\n**Categories:**\n- `media` - Video, image, podcast search\n- `documents` - Document Q&A, RAG\n- `ecommerce` - Product catalog search\n\n**To instantiate (requires auth):**\n```\nPOST /v1/templates/scaffolds/{template_id}/instantiate\n{\"namespace_name\": \"my_app\"}\n```", "operationId": "list_scaffolds_v1_public_templates_scaffolds_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category (media, documents, ecommerce)", "title": "Category" }, "description": "Filter by category (media, documents, ecommerce)" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only show active templates", "default": true, "title": "Is Active" }, "description": "Only show active templates" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseTemplateModel" }, "title": "Response List Scaffolds V1 Public Templates Scaffolds Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/scaffolds/{template_id}": { "get": { "tags": [ "Public Templates API", "Public Scaffolds" ], "summary": "Get Scaffold", "description": "Get scaffold template details (public, no auth required).\n\nReturns the complete configuration including:\n- Namespace: feature extractors, payload indexes\n- Bucket: name, description, schema\n- Collection: feature extractor config\n- Retriever: stages, input schema\n\n**To instantiate (requires auth):**\n```\nPOST /v1/templates/scaffolds/{template_id}/instantiate\n{\"namespace_name\": \"my_app\"}\n```", "operationId": "get_scaffold_v1_public_templates_scaffolds__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Scaffold template ID", "title": "Template Id" }, "description": "Scaffold template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/scaffolds/{template_id}/sample-data": { "get": { "tags": [ "Public Templates API", "Public Scaffolds" ], "summary": "Get Scaffold Sample Data", "description": "Live per-collection document counts of the scaffold's golden sample\nnamespace (public, no auth required).\n\nPowers the Studio pre-clone preview: what a user actually gets when they\nclone this scaffold with sample data. Counts are live-derived server-side\n(cached ~10 min) because golden namespaces are not readable with normal\norg keys.", "operationId": "get_scaffold_sample_data_v1_public_templates_scaffolds__template_id__sample_data_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Scaffold template ID", "title": "Template Id" }, "description": "Scaffold template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScaffoldSampleDataResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/scaffolds/{template_id}/manifest": { "get": { "tags": [ "Public Templates API", "Public Scaffolds" ], "summary": "Get Scaffold Manifest", "description": "Render a scaffold template as a Mixpeek manifest (public, no auth).\n\nPowers the Studio namespace-templates UI, which shows each template as a\ndeclarative manifest tree + copyable YAML (the same IaC format used by\n`POST /v1/manifest/apply`). Returns both the YAML string (`manifest_yaml`)\nand the parsed manifest dict (`manifest`).", "operationId": "get_scaffold_manifest_v1_public_templates_scaffolds__template_id__manifest_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Scaffold template ID", "title": "Template Id" }, "description": "Scaffold template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScaffoldManifestResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/namespaces": { "get": { "tags": [ "Public Templates API" ], "summary": "List Public Namespace Templates", "description": "List public namespace templates (no authentication required).\n\nReturns only templates marked as public (is_public=True).", "operationId": "list_public_namespace_templates_v1_public_templates_namespaces_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseTemplateModel" }, "title": "Response List Public Namespace Templates V1 Public Templates Namespaces Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/namespaces/{template_id}": { "get": { "tags": [ "Public Templates API" ], "summary": "Get Public Namespace Template", "description": "Get public namespace template details (no authentication required).\n\nReturns template only if marked as public.", "operationId": "get_public_namespace_template_v1_public_templates_namespaces__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/retrievers": { "get": { "tags": [ "Public Templates API" ], "summary": "List Public Retriever Templates", "description": "List public retriever templates (no authentication required).\n\nReturns only templates marked as public (is_public=True).", "operationId": "list_public_retriever_templates_v1_public_templates_retrievers_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseTemplateModel" }, "title": "Response List Public Retriever Templates V1 Public Templates Retrievers Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/templates/retrievers/{template_id}": { "get": { "tags": [ "Public Templates API" ], "summary": "Get Public Retriever Template", "description": "Get public retriever template details (no authentication required).\n\nReturns template only if marked as public.", "operationId": "get_public_retriever_template_v1_public_templates_retrievers__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/apps/{slug}/config": { "get": { "tags": [ "Public Apps API" ], "summary": "Get public App config", "description": "Fetch the full configuration for a public App \u2014 no authentication required.\n\nUsed by the `canvas/` host runtime and the `@mixpeek/canvas-sdk`\n`useApp()` hook to render the app. Returns tabs, hero, stats, sections,\ntheme, and SEO settings.\n\nServes the `published_config` snapshot when available, so draft edits\nmade via `PATCH /v1/apps/{app_id}` are not visible until the app is\npublished.", "operationId": "get_public_app_config_v1_public_apps__slug__config_get", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Globally unique app slug", "title": "Slug" }, "description": "Globally unique app slug" } ], "responses": { "200": { "description": "Full app configuration for UI rendering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAppConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/apps/{slug}/search": { "post": { "tags": [ "Public Apps API" ], "summary": "Execute an App tab search", "description": "Execute a search on a specific tab of a public App \u2014 no authentication required.\n\nRoutes `tab_id` \u2192 retriever \u2192 results. Each tab can be backed by either:\n- An **internal retriever** (`retriever_id`) \u2014 org-scoped\n- A **marketplace catalog entry** (`public_name`) \u2014 proxied via public API\n\nThe `inputs` dict is passed directly to the retriever's `input_schema`.\nExtra top-level fields are automatically merged into `inputs`.\n\n**Example:**\n```json\n{\n \"tab_id\": \"search\",\n \"inputs\": { \"query\": \"red sneakers\" },\n \"settings\": { \"limit\": 20 }\n}\n```", "operationId": "execute_public_app_search_v1_public_apps__slug__search_post", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Globally unique app slug", "title": "Slug" }, "description": "Globally unique app slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAppSearchRequest" } } } }, "responses": { "200": { "description": "Search results from the tab's retriever", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/apps/{slug}/gallery": { "get": { "tags": [ "Public Apps API" ], "summary": "Get App featured gallery", "description": "Fetch featured gallery results for a public App \u2014 no authentication required.\n\nExecutes the app's `featured_gallery` retriever using `default_inputs`\ndefined in the gallery configuration. Returns an empty result set if the\ngallery is disabled or not configured.", "operationId": "get_public_app_gallery_v1_public_apps__slug__gallery_get", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Globally unique app slug", "title": "Slug" }, "description": "Globally unique app slug" } ], "responses": { "200": { "description": "Featured gallery results using the gallery's default inputs", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/apps/{slug}/interactions": { "post": { "tags": [ "Public Apps API" ], "summary": "Track an App interaction event", "description": "Record a user interaction event for a public App \u2014 no authentication required.\n\nInteraction events are written to the ``app_interactions`` collection for\nanalytics and relevance tuning. Write errors are swallowed server-side so\nthat a transient storage failure never surfaces as an error to the caller.\n\n**Example:**\n```json\n{\n \"event_type\": \"click\",\n \"document_id\": \"doc_abc123\",\n \"position\": 2,\n \"query\": \"red sneakers\",\n \"session_id\": \"sess_xyz\"\n}\n```", "operationId": "track_public_app_interaction_v1_public_apps__slug__interactions_post", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Globally unique app slug", "title": "Slug" }, "description": "Globally unique app slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionRequest" } } } }, "responses": { "200": { "description": "Acknowledgement that the event was recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Track Public App Interaction V1 Public Apps Slug Interactions Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/apps/{slug}/taxonomies/{taxonomy_id}/tree": { "get": { "tags": [ "Public Apps API" ], "summary": "Get taxonomy node tree for an App", "description": "Fetch the node tree for a taxonomy associated with a public App \u2014 no authentication required.\n\nLooks up the taxonomy by ``taxonomy_id`` within the namespace that owns\nthe app identified by ``slug``. Returns the full ``nodes`` array as stored,\nwhich can be used to render faceted navigation or classification trees in\nthe app UI.", "operationId": "get_public_app_taxonomy_tree_v1_public_apps__slug__taxonomies__taxonomy_id__tree_get", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Globally unique app slug", "title": "Slug" }, "description": "Globally unique app slug" }, { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID to retrieve", "title": "Taxonomy Id" }, "description": "Taxonomy ID to retrieve" } ], "responses": { "200": { "description": "Full taxonomy node tree scoped to the App's namespace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyTreeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/extractors/": { "get": { "tags": [ "Public Extractor Marketplace" ], "summary": "List Public Extractors", "description": "Browse and search public extractors.\n\nNo authentication required. Returns active extractors sorted by install count.", "operationId": "list_public_extractors_v1_public_extractors__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Results per page", "default": 20, "title": "Page Size" }, "description": "Results per page" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Search query", "title": "Search" }, "description": "Search query" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "capability", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by capability (batch, realtime)", "title": "Capability" }, "description": "Filter by capability (batch, realtime)" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by tags (all must match)", "title": "Tags" }, "description": "Filter by tags (all must match)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicExtractorsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/public/extractors/{public_name}": { "get": { "tags": [ "Public Extractor Marketplace" ], "summary": "Get Public Extractor", "description": "Get full detail for a public extractor including manifest and readme.", "operationId": "get_public_extractor_v1_public_extractors__public_name__get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the extractor", "title": "Public Name" }, "description": "Public name of the extractor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExtractorDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/apps": { "post": { "tags": [ "Apps" ], "summary": "Create an App", "description": "Create a new App.\n\nApps are full-stack web applications deployed as zip bundles to\n``{slug}.mxp.co``. After creation, deploy your built frontend via the\ndeploy pipeline:\n\n1. ``POST /v1/apps/{app_id}/deploy/upload-url`` \u2014 get a presigned S3 PUT URL\n2. Upload your built ``dist/`` zip to that URL\n3. ``POST /v1/apps/{app_id}/deploy`` \u2014 trigger the build\n\nOnly ``slug`` and ``meta`` are required. Set ``auth_config.mode`` to\ncontrol end-user authentication (``public``, ``clerk``, ``password``,\n``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``).\n\nSlugs are globally unique across all organizations.\n\n**Deprecated fields:** ``template``, ``sections``, ``custom_html``,\n``hero``, ``theme``, ``seo``, ``stats``, ``featured_gallery``, ``tabs``,\n``password_secret_name`` are accepted for backward compatibility but\nshould not be used for new apps.\n\n**Tier limits:** Free = 1 app, Pro = 10, Enterprise = unlimited\n(``TierLimits._max_apps``). Exceeding your tier's limit returns a 400 with\nthe limit + current count in ``error.details``.", "operationId": "create_app_v1_apps_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppRequest" } } } }, "responses": { "200": { "description": "The created App configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Apps" ], "summary": "List Apps", "description": "List all Apps for this organization.\n\nThe response includes ``max_apps`` (the tier's Canvas App limit, ``null`` =\nunlimited) so the UI can render usage (\"X of N apps used\") and gate the\ncreate action without a second round-trip.", "operationId": "list_apps_v1_apps_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "template", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by template type", "title": "Template" }, "description": "Filter by template type" }, { "name": "slug", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact match on app slug", "title": "Slug" }, "description": "Exact match on app slug" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive partial match on app name", "title": "Search" }, "description": "Case-insensitive partial match on app name" } ], "responses": { "200": { "description": "Paginated list of Apps for this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAppsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}": { "get": { "tags": [ "Apps" ], "summary": "Get an App", "description": "Get an App by its `app_id`.", "operationId": "get_app_v1_apps__app_id__get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "responses": { "200": { "description": "Full App configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Apps" ], "summary": "Update an App", "description": "Partially update an App configuration (saved as draft).\n\nAll fields are optional \u2014 only the fields you provide are updated.\nUpdates are draft by default. Set `publish: true` to apply and publish\nin a single call.", "operationId": "update_app_v1_apps__app_id__patch", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppRequest" } } } }, "responses": { "200": { "description": "Updated App configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Apps" ], "summary": "Delete an App", "description": "Delete an App permanently.\n\nThe slug is freed immediately. Any active custom domains will stop\nresolving within seconds.", "operationId": "delete_app_v1_apps__app_id__delete", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/publish": { "post": { "tags": [ "Apps" ], "summary": "Publish an App", "description": "Publish the current draft config of an App.\n\nFor deploy-based apps, code deploys go live automatically \u2014 you only\nneed this endpoint to publish **config changes** (auth, meta, etc.).\n\nCreates an immutable version snapshot with a content hash.", "operationId": "publish_app_v1_apps__app_id__publish_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublishAppRequest" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "description": "The published App configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/rollback": { "post": { "tags": [ "Apps" ], "summary": "Rollback an App", "description": "Rollback to the previous published config version.\n\nFor deploy-based apps, use ``POST /v1/apps/{app_id}/versions/{version}/restore``\nto roll back to any previous code deploy instead.", "operationId": "rollback_app_v1_apps__app_id__rollback_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "responses": { "200": { "description": "The restored App configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/domains": { "post": { "tags": [ "Apps" ], "summary": "Add a custom domain", "description": "Attach a custom domain to an App.\n\nReturns a `verification_token` and `cname_target`. To prove ownership,\nadd a DNS TXT record:\n\n _mixpeek-verify.{domain} TXT \"mixpeek-site-verification={verification_token}\"\n\nThen call `POST /{app_id}/domains/{domain}/verify` to start polling.", "operationId": "add_domain_v1_apps__app_id__domains_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomainRequest" } } } }, "responses": { "200": { "description": "The newly added domain configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Apps" ], "summary": "List custom domains", "description": "List all custom domains attached to an App.", "operationId": "list_domains_v1_apps__app_id__domains_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "responses": { "200": { "description": "All custom domains attached to the App", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/domains/{domain}/verify": { "post": { "tags": [ "Apps" ], "summary": "Trigger DNS verification", "description": "Trigger asynchronous DNS TXT record verification for a domain.\n\nThe domain status is set to `verifying` immediately. A Celery worker\npolls DNS every 30 minutes for up to 72 hours. On success the status\nadvances to `provisioning_tls`.", "operationId": "verify_domain_v1_apps__app_id__domains__domain__verify_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "description": "Domain to verify (e.g. search.acme.com)", "title": "Domain" }, "description": "Domain to verify (e.g. search.acme.com)" } ], "responses": { "200": { "description": "Domain record with status set to 'verifying'", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/domains/{domain}": { "delete": { "tags": [ "Apps" ], "summary": "Remove a domain", "description": "Remove a custom domain from an App.", "operationId": "delete_domain_v1_apps__app_id__domains__domain__delete", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "description": "Domain to remove (e.g. search.acme.com)", "title": "Domain" }, "description": "Domain to remove (e.g. search.acme.com)" } ], "responses": { "200": { "description": "Deletion confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users": { "get": { "tags": [ "Apps" ], "summary": "List app users", "description": "List all users in this app's Clerk organization.", "operationId": "list_app_users_v1_apps__app_id__users_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users/invite": { "post": { "tags": [ "Apps" ], "summary": "Invite a user", "description": "Invite a user to this app by email via Clerk.", "operationId": "invite_app_user_v1_apps__app_id__users_invite_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUserRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInvitationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users/{user_id}": { "delete": { "tags": [ "Apps" ], "summary": "Remove a user", "description": "Remove a user from this app's Clerk organization.", "operationId": "remove_app_user_v1_apps__app_id__users__user_id__delete", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Clerk user ID", "title": "User Id" }, "description": "Clerk user ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users/{user_id}/role": { "patch": { "tags": [ "Apps" ], "summary": "Update user role", "description": "Update a user's role in this app's Clerk organization.", "operationId": "update_app_user_role_v1_apps__app_id__users__user_id__role_patch", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Clerk user ID", "title": "User Id" }, "description": "Clerk user ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppUserResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users/invitations": { "get": { "tags": [ "Apps" ], "summary": "List pending invitations", "description": "List pending invitations for this app's Clerk organization.", "operationId": "list_app_invitations_v1_apps__app_id__users_invitations_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInvitationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/users/invitations/{invitation_id}": { "delete": { "tags": [ "Apps" ], "summary": "Revoke an invitation", "description": "Revoke a pending invitation.", "operationId": "revoke_app_invitation_v1_apps__app_id__users_invitations__invitation_id__delete", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID", "title": "App Id" }, "description": "App ID" }, { "name": "invitation_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Clerk invitation ID", "title": "Invitation Id" }, "description": "Clerk invitation ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/deploy/upload-url": { "post": { "tags": [ "Apps" ], "summary": "Get presigned upload URL", "description": "Generate a presigned S3 PUT URL so the CLI can upload a bundle zip directly.\nPass the returned `bundle_s3_key` to the deploy endpoint.", "operationId": "get_upload_url_v1_apps__app_id__deploy_upload_url_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/deploy/verify-upload": { "post": { "tags": [ "Apps" ], "summary": "Verify a presigned-URL upload landed in S3", "description": "Confirm a bundle uploaded via a presigned PUT URL actually landed in S3.\n\nS3 returns an empty body on a successful PUT \u2014 the ETag is only in\nresponse headers, which browser clients often can't read due to CORS.\nThis endpoint does a server-side HEAD and returns {etag, size_bytes,\nlast_modified, exists} so clients can verify the upload before calling\n`/deploy`.", "operationId": "verify_upload_v1_apps__app_id__deploy_verify_upload_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/deploy": { "post": { "tags": [ "Apps" ], "summary": "Deploy an App", "description": "Queue a build+deploy for an App, creating a new version.\n\n**Full deploy workflow:**\n1. `POST /{app_id}/deploy/upload-url` \u2192 get a presigned S3 PUT URL\n2. Upload your built dist/ zip to that URL\n3. Call this endpoint with the returned `bundle_s3_key`\n4. Optionally include `source_files` (path\u2192content map) for version diffing\n5. Poll `GET /{app_id}/deploys/{deploy_id}` until status is `complete`\n\n**Edit-and-redeploy workflow:**\n1. `GET /{app_id}/versions/{version}/download` \u2192 download the bundle zip\n2. Edit files locally\n3. Re-zip and upload via upload-url \u2192 deploy (creates a new version)\n4. `GET /{app_id}/versions/{old}/diff/{new}` to review changes\n\nEach deploy creates an immutable version record. Use `POST /{app_id}/versions/{n}/restore`\nfor instant rollback to any previous version.", "operationId": "deploy_app_v1_apps__app_id__deploy_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/versions": { "get": { "tags": [ "Apps" ], "summary": "List version history", "description": "Return version history for an App, most recent first.", "operationId": "list_versions_v1_apps__app_id__versions_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/versions/{version}/restore": { "post": { "tags": [ "Apps" ], "summary": "Restore a previous version", "description": "Restore a previous version by pointing the environment to its assets.\n\nThis is instant \u2014 no rebuild required. Old assets are always retained in S3.", "operationId": "restore_version_v1_apps__app_id__versions__version__restore_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "description": "Version number to restore", "title": "Version" }, "description": "Version number to restore" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreVersionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreVersionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/versions/{version}": { "get": { "tags": [ "Apps" ], "summary": "Get version details", "description": "Return full details for a specific version including asset manifest and source files.", "operationId": "get_version_v1_apps__app_id__versions__version__get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "description": "Version number", "title": "Version" }, "description": "Version number" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/versions/{version}/download": { "get": { "tags": [ "Apps" ], "summary": "Download a version's bundle", "description": "Get a presigned download URL for a version's original bundle zip.\n\nUse this to download \u2192 edit \u2192 re-upload \u2192 deploy as a new version.\nThe returned URL expires in 1 hour.", "operationId": "download_version_v1_apps__app_id__versions__version__download_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "description": "Version number to download", "title": "Version" }, "description": "Version number to download" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrlResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/versions/{from_version}/diff/{to_version}": { "get": { "tags": [ "Apps" ], "summary": "Diff two versions", "description": "Compare two versions \u2014 returns file-level changes and optional source diffs.\n\nLike `git diff v1..v2`: shows added, removed, modified, and unchanged files\nbased on content hashes. If both versions have source_files, also returns\nunified diffs of the source code.", "operationId": "diff_versions_v1_apps__app_id__versions__from_version__diff__to_version__get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "from_version", "in": "path", "required": true, "schema": { "type": "integer", "description": "Base version", "title": "From Version" }, "description": "Base version" }, { "name": "to_version", "in": "path", "required": true, "schema": { "type": "integer", "description": "Target version", "title": "To Version" }, "description": "Target version" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionDiffResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/deploys/{deploy_id}": { "get": { "tags": [ "Apps" ], "summary": "Get deploy status", "description": "Check the status of a specific deployment (queued, building, complete, failed).", "operationId": "get_deploy_status_v1_apps__app_id__deploys__deploy_id__get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "deploy_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Deploy ID", "title": "Deploy Id" }, "description": "Deploy ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/deploys/{deploy_id}/logs/stream": { "get": { "tags": [ "Apps" ], "summary": "Stream deploy logs (SSE)", "description": "Server-Sent Events stream of real-time deploy logs.\n\nSends cached logs first (catch-up), then subscribes to live log\nevents via Redis pub/sub until the deploy reaches a terminal state.", "operationId": "stream_deploy_logs_v1_apps__app_id__deploys__deploy_id__logs_stream_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "deploy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deploy Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/promote": { "post": { "tags": [ "Apps" ], "summary": "Promote staging to production", "description": "Promote the current staging deployment to production.\n\nCopies `environments.staging` (deploy_id, asset_prefix) to\n`environments.production` and updates `build_config.asset_prefix`\nfor backward compatibility. Also invalidates the canvas asset cache\nso the new production version is served immediately.", "operationId": "promote_app_v1_apps__app_id__promote_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "description": "App ID (e.g. app_abc123def456)", "title": "App Id" }, "description": "App ID (e.g. app_abc123def456)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/connect-repo": { "post": { "tags": [ "Apps" ], "summary": "Connect a GitHub repository", "description": "Connect a GitHub repository for automatic deploys on push.\n\nAfter connecting, pushes to the configured branch will trigger\na build + deploy via the GitHub App webhook.", "operationId": "connect_repo_v1_apps__app_id__connect_repo_post", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectRepoRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Apps" ], "summary": "Disconnect GitHub repository", "description": "Disconnect the GitHub repository from this app.", "operationId": "disconnect_repo_v1_apps__app_id__connect_repo_delete", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/github/install-url": { "get": { "tags": [ "Apps" ], "summary": "Get the GitHub App install URL for this app", "description": "Return the GitHub App installation URL carrying a signed ``state``.\n\nThe Studio \"Install GitHub App\" button opens this URL; after install,\nGitHub redirects to ``/webhooks/apps/github/setup`` which verifies the\nsignature and links the installation to this app.", "operationId": "github_install_url_v1_apps__app_id__github_install_url_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/error-rate": { "get": { "tags": [ "Apps" ], "summary": "Get recent error rate", "description": "Query ClickHouse canvas_errors for the error count in the last N minutes.", "operationId": "get_error_rate_v1_apps__app_id__error_rate_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "minutes", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1440, "minimum": 1, "description": "Lookback window in minutes", "default": 60, "title": "Minutes" }, "description": "Lookback window in minutes" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorRateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/analytics": { "get": { "tags": [ "Apps" ], "summary": "Get app analytics overview", "description": "Per-app analytics dashboard data: error trend, Web Vitals, recent errors, event counts.\n\nQueries ClickHouse canvas_errors, canvas_vitals, and canvas_app_events tables.", "operationId": "get_app_analytics_v1_apps__app_id__analytics_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Lookback window in hours", "default": 24, "title": "Hours" }, "description": "Lookback window in hours" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppAnalyticsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/apps/{app_id}/logs": { "get": { "tags": [ "Apps" ], "summary": "Get runtime or request logs", "description": "Query ClickHouse canvas_app_logs or canvas_request_logs.", "operationId": "get_app_logs_v1_apps__app_id__logs_get", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "title": "App Id" } }, { "name": "log_type", "in": "query", "required": false, "schema": { "enum": [ "runtime", "requests" ], "type": "string", "description": "Which log stream: 'runtime' (console/app logs from canvas_app_logs) or 'requests' (HTTP request logs from canvas_request_logs). Any other value is a 422 naming these \u2014 previously 'request' (singular) silently fell through to the runtime branch and returned nothing.", "default": "runtime", "title": "Log Type" }, "description": "Which log stream: 'runtime' (console/app logs from canvas_app_logs) or 'requests' (HTTP request logs from canvas_request_logs). Any other value is a 422 naming these \u2014 previously 'request' (singular) silently fell through to the runtime branch and returned nothing." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 168, "minimum": 1, "description": "Lookback window in hours", "default": 1, "title": "Hours" }, "description": "Lookback window in hours" }, { "name": "level", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by log level (runtime only)", "title": "Level" }, "description": "Filter by log level (runtime only)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Max entries", "default": 100, "title": "Limit" }, "description": "Max entries" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppLogsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "List change feed events", "description": "List this organization's change feed, ordered and resumable by cursor.\n\nA consumer can be killed mid-stream and resume from its last stored\n`next_cursor` without re-reading or missing anything, **as long as it\nresumes within the 90-day retention window** \u2014 events older than that\nare permanently expired, not archived. A consumer that has been down\nlonger than 90 days must resync current state instead of resuming.\n\nA cursor is only meaningful for a FIXED filter set: it encodes a\nposition in this organization's overall sequence, not a position\nwithin any particular `namespace_id`/`event_type` filter. Changing\neither filter mid-stream while reusing an old cursor silently skips\nwhatever the previous filter combination would have matched in\nbetween \u2014 start a fresh cursor (or none) whenever the filters change.", "operationId": "list_events_v1_events_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from a prior response's next_cursor. Omit to start from the beginning of the 90-day retention window.", "title": "Cursor" }, "description": "Opaque cursor from a prior response's next_cursor. Omit to start from the beginning of the 90-day retention window." }, { "name": "namespace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to events scoped to one namespace.", "title": "Namespace Id" }, "description": "Filter to events scoped to one namespace." }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "type": "null" } ], "description": "Filter to one event type.", "title": "Event Type" }, "description": "Filter to one event type." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/health/liveness": { "get": { "tags": [ "Health" ], "summary": "Liveness", "description": "Lightweight liveness probe for container orchestration (Render, K8s).\n\nThis endpoint returns immediately without checking external services.\nUse this for Render health checks to avoid timeouts when services are slow.", "operationId": "liveness_v1_health_liveness_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/health/beat": { "get": { "tags": [ "Health" ], "summary": "Celery Beat Health", "description": "Check if Celery Beat scheduler is running.\n\nReads the heartbeat timestamp from Redis (written every 60s by beat).\nReturns unhealthy if heartbeat is older than 5 minutes.", "operationId": "celery_beat_health_v1_health_beat_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Healthcheck", "description": "Lightweight health check \u2014 confirms the process is alive and the event loop\nis responding. Completes in <10ms with no external service calls.\n\nUse ``GET /v1/health/deep`` for the full service-level health check.", "operationId": "healthcheck_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/health/deep": { "get": { "tags": [ "Health" ], "summary": "Healthcheck Deep", "description": "Full health check \u2014 pings every dependent service with aggressive per-service\ntimeouts (500ms) so total wall time stays under ~3s even when a service is slow.\n\nUse the ``deep=true`` query parameter for additional data-plane verification\n(e.g. reading from MongoDB collections, probing MVS namespaces, inspecting\nCelery workers).", "operationId": "healthcheck_deep_v1_health_deep_get", "parameters": [ { "name": "deep", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Deep" } }, { "name": "metrics", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include Layer 2 protection metrics", "default": false, "title": "Metrics" }, "description": "Include Layer 2 protection metrics" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/resources/search": { "post": { "tags": [ "Resource Search" ], "summary": "Search Resources", "description": "Search across all resource names and IDs within your namespace.\n\n This endpoint performs a case-insensitive search across:\n - Buckets (bucket_name, bucket_id)\n - Collections (collection_name, collection_id)\n - Retrievers (retriever_name, retriever_id)\n - Taxonomies (taxonomy_name, taxonomy_id)\n - Clusters (cluster_name, cluster_id)\n - Namespaces (namespace_name, namespace_id)\n\n Results are sorted by relevance (exact matches first) and creation time (newest first).\n Use the resource_types parameter to filter searches to specific resource types.\n Pagination is supported via limit and offset parameters.", "operationId": "search_resources_v1_resources_search_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/features/extractors": { "get": { "tags": [ "Feature Extractors" ], "summary": "List Feature Extractors", "description": "List all available feature extractors grouped by category", "operationId": "list_feature_extractors_v1_collections_features_extractors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FeatureExtractorResponseModel" }, "type": "array", "title": "Response List Feature Extractors V1 Collections Features Extractors Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/collections/features/extractors/{feature_extractor_id}": { "get": { "tags": [ "Feature Extractors" ], "summary": "Get Feature Extractor by Name", "description": "Get detailed information about a specific feature extractor by its name", "operationId": "get_feature_extractor_by_id_v1_collections_features_extractors__feature_extractor_id__get", "parameters": [ { "name": "feature_extractor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Feature Extractor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureExtractorResponseModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/collections/features": { "get": { "tags": [ "Features" ], "summary": "Discover Features", "description": "The menu of what you can search by: each file type (modality), its billing unit, and the search features available on it (with rates). Feature keys are the values accepted by collection config `features: [...]`. No authentication required.", "operationId": "discover_features_v1_collections_features_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureDiscoveryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/features/search": { "post": { "tags": [ "Feature Search" ], "summary": "Feature Search", "description": "Search documents by vector similarity across collections. A convenience wrapper that builds an ad-hoc retriever with a single feature_search stage.", "operationId": "feature_search_v1_features_search_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections": { "post": { "tags": [ "Collections" ], "summary": "Create Collection", "description": "Create a new processing collection linked to a namespace.\n\nA collection defines the feature extraction pipeline that runs when objects are\nuploaded to a bucket. One feature extractor per collection.\n\n**Custom plugin collections:**\n\nWhen `feature_extractor_name` references a custom plugin, the collection's vector\nindexes are read from the plugin's `manifest.py` `features` list. The `features`\nentries **must** use these exact key names \u2014 wrong keys silently produce a collection\nwith no vector indexes and 0 documents will be written:\n\n```json\n{\n \"feature_type\": \"embedding\",\n \"feature_name\": \"my_embedding\",\n \"embedding_dim\": 768,\n \"distance_metric\": \"cosine\"\n}\n```\n\nCommon wrong keys (will be ignored): `type`, `name`, `dimensions`, `distance`.\n\n**Vector schema:** Custom plugin vectors are automatically added to the namespace's\nQdrant collection the first time a batch is processed, so there is no need to recreate\nthe namespace when adding a plugin with new embedding types.", "operationId": "create_collection_v1_collections_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Collections" ], "summary": "List Collections (GET)", "description": "GET-friendly alias for `POST /v1/collections/list`. Supports the same\n pagination/search semantics via query parameters. The namespace is taken\n from the `X-Namespace` header (`namespace_id` query parameter is accepted\n but ignored \u2014 namespace scoping is always header-based).", "operationId": "list_collections_get_v1_collections_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search over collection names", "title": "Search" }, "description": "Free-text search over collection names" }, { "name": "namespace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ignored \u2014 set X-Namespace header", "title": "Namespace Id" }, "description": "Ignored \u2014 set X-Namespace header" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCollectionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/clone": { "post": { "tags": [ "Collections" ], "summary": "Clone Collection", "description": "Clone a collection with optional modifications.\n\n **Purpose:**\n Creates a NEW collection (with new ID) based on an existing one. This is the\n recommended way to iterate on collection designs when you need to modify core\n configuration that PATCH doesn't allow (source, feature_extractor, field_passthrough).\n\n **Clone vs PATCH vs Template:**\n - **PATCH**: Update metadata only (enabled, metadata, taxonomy_applications)\n - **Clone**: Copy and modify core configuration (source, feature_extractor)\n - **Template**: Start from a pre-configured pattern (for new projects)\n\n **Common Use Cases:**\n - Change feature extractor configuration (model, parameters)\n - Modify field_passthrough to include/exclude fields\n - Switch to different source (bucket or collection)\n - Test modifications before replacing production collection\n - Create variants (e.g., different embedding models)\n\n **How it works:**\n 1. Source collection is copied\n 2. You provide a new name (REQUIRED)\n 3. Optionally override any other fields\n 4. A new collection is created with a new ID\n 5. Original collection remains unchanged", "operationId": "clone_collection_v1_collections__collection_identifier__clone_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Source collection ID or name to clone.", "title": "Collection Identifier" }, "description": "Source collection ID or name to clone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneCollectionRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneCollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/trigger": { "post": { "tags": [ "Collections" ], "summary": "Trigger Collection Processing", "description": "Process data through a collection - works for both bucket-sourced and collection-sourced collections.\n\n **For bucket-sourced collections:**\n Discovers objects from source bucket(s), creates a batch, and submits for processing.\n Use `include_buckets` to limit which source buckets to process from.\n\n **For collection-sourced collections:**\n Processes existing documents from upstream collection(s).\n Use `include_collections` to limit which source collections to process from.\n\n **Filtering:**\n - `source_filters`: Field-level filters using LogicalOperator format\n - Example: `{\"AND\": [{\"field\": \"status\", \"operator\": \"eq\", \"value\": \"pending\"}]}`\n - For specific objects: `{\"AND\": [{\"field\": \"object_id\", \"operator\": \"in\", \"value\": [\"obj_1\", \"obj_2\"]}]}`\n\n **Returns:**\n - batch_id: Track progress via GET /batches/{batch_id}\n - task_id: Monitor via GET /tasks/{task_id}", "operationId": "trigger_collection_v1_collections__collection_identifier__trigger_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to trigger", "title": "Collection Identifier" }, "description": "The ID or name of the collection to trigger" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCollectionRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}": { "get": { "tags": [ "Collections" ], "summary": "Get Collection", "description": "This endpoint allows you to retrieve a collection by ID or name.", "operationId": "get_collection_v1_collections__collection_identifier__get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to retrieve", "title": "Collection Identifier" }, "description": "The ID or name of the collection to retrieve" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Collections" ], "summary": "Update Collection", "description": "Update mutable collection fields (collection_name, description, taxonomy_applications, enabled)", "operationId": "update_collection_v1_collections__collection_identifier__patch", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to update", "title": "Collection Identifier" }, "description": "The ID or name of the collection to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Updates" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Collections" ], "summary": "Delete Collection", "description": "This endpoint deletes a collection and all its resources including:\n - Qdrant points (documents) with this collection_id\n - Cache entries\n - MongoDB collection metadata\n\n Note: Collections are payload IDs within the namespace's Qdrant collection,\n not separate Qdrant collections.\n\n The deletion is performed synchronously and returns when complete.", "operationId": "delete_collection_v1_collections__collection_identifier__delete", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to delete", "title": "Collection Identifier" }, "description": "The ID or name of the collection to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/features": { "get": { "tags": [ "Collections" ], "summary": "Describe collection features", "description": "List feature addresses and metadata available in this collection", "operationId": "describe_collection_features_route_v1_collections__collection_identifier__features_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to describe", "title": "Collection Identifier" }, "description": "The ID or name of the collection to describe" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeCollectionFeaturesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/export": { "post": { "tags": [ "Collections" ], "summary": "Export Collection", "description": "Export collection documents to JSON, CSV, or Parquet format.\n\n **Export Formats:**\n - **JSON**: Line-delimited JSON (JSONL) format. Good for streaming.\n - **CSV**: Comma-separated values. Best for spreadsheets.\n - **PARQUET**: Columnar format (default). Best for data pipelines.\n\n **Vector Export:**\n Vectors are large and exported separately. When `include_vectors=True`,\n a separate file is created for vectors with document_id mapping.\n\n **Field Selection:**\n Use `select_fields` to export only specific fields, reducing file size.\n\n **Filtering:**\n Apply filters to export a subset of documents.\n\n **Response:**\n Returns presigned download URLs valid for 1 hour.\n\n **Limits:**\n - Large exports may take time. Consider using `sample_size` for testing.\n - Vector exports significantly increase processing time.", "operationId": "export_collection_v1_collections__collection_identifier__export_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection to export", "title": "Collection Identifier" }, "description": "The ID or name of the collection to export" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionExportRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionExportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/list": { "post": { "tags": [ "Collections" ], "summary": "List Collections", "description": "This endpoint allows you to list collections.", "operationId": "list_collections_v1_collections_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCollectionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCollectionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/lifecycle": { "get": { "tags": [ "Collection Lifecycle" ], "summary": "Get Lifecycle Status", "description": "Get the storage lifecycle status of a collection including vector counts.", "operationId": "get_lifecycle_v1_collections__collection_identifier__lifecycle_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID or name", "title": "Collection Identifier" }, "description": "Collection ID or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Collection Lifecycle" ], "summary": "Transition Lifecycle", "description": "Transition a collection's storage tier. 'cold' evicts from the vector store (vectors searchable via object storage). 'active' rehydrates back to the vector store. 'archived' permanently removes vectors.", "operationId": "transition_lifecycle_v1_collections__collection_identifier__lifecycle_patch", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID or name", "title": "Collection Identifier" }, "description": "Collection ID or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionLifecycleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_id}/sync-schema": { "post": { "tags": [ "Collection Schema" ], "summary": "Sync Collection Schema", "description": "Sample documents from Qdrant and automatically discover new fields to add to the collection's output_schema.\n\n This endpoint:\n - Samples N documents from the collection (default: 1000)\n - Discovers all fields present in actual documents\n - Merges discovered fields into the collection's output_schema (additive only)\n - Optionally cascades schema updates to downstream collections\n - Respects debounce window (max once per 5 minutes, unless force=true)\n\n The sync operation is additive only - it never removes or changes existing field types.\n\n Use this endpoint to:\n - Manually trigger schema discovery after data ingestion\n - Force an immediate schema sync (bypassing debounce)\n - Update schemas with new fields discovered in documents", "operationId": "sync_collection_schema_v1_collections__collection_id__sync_schema_post", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID to sync schema for", "title": "Collection Id" }, "description": "Collection ID to sync schema for" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaSyncRequest", "default": { "sample_size": 1000, "force": false, "cascade_to_downstream": true } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSyncResponse" }, { "$ref": "#/components/schemas/SchemaSyncSkippedResponse" } ], "title": "Response Sync Collection Schema V1 Collections Collection Id Sync Schema Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/count": { "get": { "tags": [ "Collection Documents" ], "summary": "Count documents in a collection.", "description": "Return the total number of documents in the collection. This is the obvious REST endpoint for a document count; it is declared before the `/{document_id}` route so the literal `count` segment is never matched as a document id (which previously produced a misleading 404).", "operationId": "count_documents_endpoint_v1_collections__collection_identifier__documents_count_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to count documents in.", "title": "Collection Identifier" }, "description": "The ID of the collection to count documents in." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCountResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/{document_id}": { "get": { "tags": [ "Collection Documents" ], "summary": "Get a document by ID.", "description": "Get a document by ID.", "operationId": "get_document_v1_collections__collection_identifier__documents__document_id__get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to retrieve.", "title": "Document Id" }, "description": "The ID of the document to retrieve." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage", "default": false, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage" }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Return Vectors" } }, { "name": "return_vector_names", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include a '_vectors' field listing available vector names for this document (without actual embedding data)", "default": false, "title": "Return Vector Names" }, "description": "Include a '_vectors' field listing available vector names for this document (without actual embedding data)" }, { "name": "expand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated fields to resolve inline under an '_expanded' key. Reserved lineage keywords: 'parent' (immediate upstream document), 'root_object' (originating bucket object), 'ancestors' (full chain root \u2192 parent), 'children' (direct downstream documents, max 100). Any other value is treated as a user field path containing doc_* references (supports dot-notation, e.g. 'items.product_id'). Max 50 unique references for non-lineage fields. Depth is limited to 1 (no recursive expansion).", "title": "Expand" }, "description": "Comma-separated fields to resolve inline under an '_expanded' key. Reserved lineage keywords: 'parent' (immediate upstream document), 'root_object' (originating bucket object), 'ancestors' (full chain root \u2192 parent), 'children' (direct downstream documents, max 100). Any other value is treated as a user field path containing doc_* references (supports dot-notation, e.g. 'items.product_id'). Max 50 unique references for non-lineage fields. Depth is limited to 1 (no recursive expansion)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "put": { "tags": [ "Collection Documents" ], "summary": "Update Document", "description": "Update a document by ID.", "operationId": "update_document_v1_collections__collection_identifier__documents__document_id__put", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to update.", "title": "Document Id" }, "description": "The ID of the document to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Collection Documents" ], "summary": "Patch Document", "description": "Partially update a document by ID (PATCH operation).", "operationId": "patch_document_v1_collections__collection_identifier__documents__document_id__patch", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to patch.", "title": "Document Id" }, "description": "The ID of the document to patch." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDocumentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Collection Documents" ], "summary": "Delete a document by ID.", "description": "Delete a document by ID.", "operationId": "delete_document_v1_collections__collection_identifier__documents__document_id__delete", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to delete.", "title": "Document Id" }, "description": "The ID of the document to delete." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/{document_id}/ancestors": { "get": { "tags": [ "Collection Documents" ], "summary": "Get document ancestors (lineage chain root \u2192 parent).", "description": "Return every prior step in this document's lineage chain, in order from\nroot through immediate parent. Excludes the document itself.\n\nEquivalent to ``GET /documents/{id}?expand=ancestors`` but returns just\nthe ancestor list \u2014 convenient for SDKs and the Studio decomposition tree.", "operationId": "get_document_ancestors_v1_collections__collection_identifier__documents__document_id__ancestors_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection.", "title": "Collection Identifier" }, "description": "The ID or name of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document.", "title": "Document Id" }, "description": "The ID of the document." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponse" }, "title": "Response Get Document Ancestors V1 Collections Collection Identifier Documents Document Id Ancestors Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/{document_id}/descendants": { "get": { "tags": [ "Collection Documents" ], "summary": "Get direct downstream documents (depth=1 children).", "description": "Return direct downstream documents (depth=1) \u2014 every document whose\n`_internal.lineage.source_document_id` equals this document's ID.\n\nCapped at 100 children per request. Equivalent to\n``GET /documents/{id}?expand=children`` but returns just the children.\n\nDeeper traversal (descendants beyond depth=1) is not yet supported in\na single call \u2014 walk recursively client-side or filter the namespace by\n``from_object`` and post-process.", "operationId": "get_document_descendants_v1_collections__collection_identifier__documents__document_id__descendants_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection.", "title": "Collection Identifier" }, "description": "The ID or name of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document.", "title": "Document Id" }, "description": "The ID of the document." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponse" }, "title": "Response Get Document Descendants V1 Collections Collection Identifier Documents Document Id Descendants Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/list": { "post": { "tags": [ "Collection Documents" ], "summary": "List documents.", "description": "List documents with optional grouping support.\n\nSupports two modes:\n1. Regular listing: Returns flat list of documents with pagination\n2. Grouped listing: When group_by is specified, returns documents grouped by field value\n\nWhen using group_by:\n- Requires a payload index on the specified field in Qdrant\n- Pagination applies to groups, not individual documents\n- Each group contains all documents sharing the same field value", "operationId": "list_documents_v1_collections__collection_identifier__documents_list_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to list documents from.", "title": "Collection Identifier" }, "description": "The ID of the collection to list documents from." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either is true, presigning is enabled.", "default": false, "title": "Return Presigned Urls" }, "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either is true, presigning is enabled." }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include vector embeddings in results. Also accepted as a body field \u2014 if either is true, vectors are returned.", "default": false, "title": "Return Vectors" }, "description": "Include vector embeddings in results. Also accepted as a body field \u2014 if either is true, vectors are returned." }, { "name": "filters", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL-encoded JSON filter (LogicalOperator shape: {\"AND\":[{\"field\":\"metadata.status\",\"operator\":\"eq\",\"value\":\"active\"}]}; OR/NOT also supported). Applies to the GET listing. POST /documents/list callers should send `filters` in the JSON body instead \u2014 the body wins when both are present. Invalid JSON returns 422 (never silently ignored).", "title": "Filters" }, "description": "URL-encoded JSON filter (LogicalOperator shape: {\"AND\":[{\"field\":\"metadata.status\",\"operator\":\"eq\",\"value\":\"active\"}]}; OR/NOT also supported). Applies to the GET listing. POST /documents/list callers should send `filters` in the JSON body instead \u2014 the body wins when both are present. Invalid JSON returns 422 (never silently ignored)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search across common document fields. Body `search` wins when both are set.", "title": "Search" }, "description": "Free-text search across common document fields. Body `search` wins when both are set." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec as JSON ({\"field\":\"created_at\",\"direction\":\"desc\"}) or the compact \"field:direction\" form. Body `sort` wins when both are set.", "title": "Sort" }, "description": "Sort spec as JSON ({\"field\":\"created_at\",\"direction\":\"desc\"}) or the compact \"field:direction\" form. Body `sort` wins when both are set." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents": { "get": { "tags": [ "Collection Documents" ], "summary": "List documents.", "description": "List documents with optional grouping support.\n\nSupports two modes:\n1. Regular listing: Returns flat list of documents with pagination\n2. Grouped listing: When group_by is specified, returns documents grouped by field value\n\nWhen using group_by:\n- Requires a payload index on the specified field in Qdrant\n- Pagination applies to groups, not individual documents\n- Each group contains all documents sharing the same field value", "operationId": "list_documents_v1_collections__collection_identifier__documents_get", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to list documents from.", "title": "Collection Identifier" }, "description": "The ID of the collection to list documents from." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either is true, presigning is enabled.", "default": false, "title": "Return Presigned Urls" }, "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either is true, presigning is enabled." }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include vector embeddings in results. Also accepted as a body field \u2014 if either is true, vectors are returned.", "default": false, "title": "Return Vectors" }, "description": "Include vector embeddings in results. Also accepted as a body field \u2014 if either is true, vectors are returned." }, { "name": "filters", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL-encoded JSON filter (LogicalOperator shape: {\"AND\":[{\"field\":\"metadata.status\",\"operator\":\"eq\",\"value\":\"active\"}]}; OR/NOT also supported). Applies to the GET listing. POST /documents/list callers should send `filters` in the JSON body instead \u2014 the body wins when both are present. Invalid JSON returns 422 (never silently ignored).", "title": "Filters" }, "description": "URL-encoded JSON filter (LogicalOperator shape: {\"AND\":[{\"field\":\"metadata.status\",\"operator\":\"eq\",\"value\":\"active\"}]}; OR/NOT also supported). Applies to the GET listing. POST /documents/list callers should send `filters` in the JSON body instead \u2014 the body wins when both are present. Invalid JSON returns 422 (never silently ignored)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search across common document fields. Body `search` wins when both are set.", "title": "Search" }, "description": "Free-text search across common document fields. Body `search` wins when both are set." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec as JSON ({\"field\":\"created_at\",\"direction\":\"desc\"}) or the compact \"field:direction\" form. Body `sort` wins when both are set.", "title": "Sort" }, "description": "Sort spec as JSON ({\"field\":\"created_at\",\"direction\":\"desc\"}) or the compact \"field:direction\" form. Body `sort` wins when both are set." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "post": { "tags": [ "Collection Documents" ], "summary": "Create a document.", "description": "Create a document by ID.", "operationId": "create_document_v1_collections__collection_identifier__documents_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/bulk": { "patch": { "tags": [ "Collection Documents" ], "summary": "Bulk Update Documents", "description": "Bulk update documents matching filter conditions.\n\nPartially updates all documents in the collection that match the provided filters.\nIf no filters are provided, updates all documents in the collection.\n\nThis endpoint applies the SAME update_data to ALL documents matching the filters.\nFor per-document updates with different values, use POST /batch endpoint instead.", "operationId": "bulk_update_documents_v1_collections__collection_identifier__documents_bulk_patch", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to update documents in.", "title": "Collection Identifier" }, "description": "The ID of the collection to update documents in." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/batch": { "post": { "tags": [ "Collection Documents" ], "summary": "Batch Update Documents", "description": "Batch update multiple documents by explicit IDs or filters.\n\nSupports TWO modes:\n1. Explicit IDs mode: Provide 'updates' array with document_id + update_data for each document\n - Each document can have DIFFERENT update_data\n - Returns detailed per-document results\n\n2. Filter mode: Provide 'filters' + 'update_data' to update all matching documents\n - All documents receive the SAME update_data\n - Returns total count only\n\nKey Features:\n- Update any document field except vectors (metadata, internal_metadata, source_blobs, etc.)\n- Maximum 1000 documents per batch in explicit mode\n- Per-document success/failure reporting in explicit mode\n- Validates documents exist in the specified collection\n\nExamples:\n Explicit IDs mode:\n ```json\n {\n \"updates\": [\n {\"document_id\": \"doc_123\", \"update_data\": {\"metadata\": {\"status\": \"processed\"}}},\n {\"document_id\": \"doc_456\", \"update_data\": {\"metadata\": {\"status\": \"archived\"}}}\n ]\n }\n ```\n\n Filter mode (logical AND/OR/NOT shape \u2014 NOT MVS-native must/key):\n ```json\n {\n \"filters\": {\"AND\": [{\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"pending\"}]},\n \"update_data\": {\"metadata\": {\"status\": \"processed\"}}\n }\n ```", "operationId": "batch_update_documents_v1_collections__collection_identifier__documents_batch_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to update documents in.", "title": "Collection Identifier" }, "description": "The ID of the collection to update documents in." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Collection Documents" ], "summary": "Batch Delete Documents", "description": "Batch delete multiple documents by explicit IDs or filters.\n\nSupports TWO modes:\n1. Explicit IDs mode: Provide 'document_ids' array\n - Deletes specific documents by ID\n - Returns detailed per-document results\n - Maximum 1000 documents per batch\n\n2. Filter mode: Provide 'filters' to delete all matching documents\n - Deletes ALL documents matching the filters\n - Returns total count only\n - Use with caution - can delete many documents\n\nKey Features:\n- Per-document success/failure reporting in explicit mode\n- Validates documents exist in the specified collection\n- Automatic document count update for the collection\n- Efficient bulk deletion\n\nExamples:\n Explicit IDs mode:\n ```json\n {\n \"document_ids\": [\"doc_123\", \"doc_456\", \"doc_789\"]\n }\n ```\n\n Filter mode (logical AND/OR/NOT shape \u2014 NOT MVS-native must/key):\n ```json\n {\n \"filters\": {\"AND\": [{\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"archived\"}]}\n }\n ```", "operationId": "batch_delete_documents_v1_collections__collection_identifier__documents_batch_delete", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection to delete documents from.", "title": "Collection Identifier" }, "description": "The ID of the collection to delete documents from." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/schema/validate": { "post": { "tags": [ "Collection Documents" ], "summary": "Validate document against collection schema", "description": "Dry-run validation: checks a document payload against the collection's document_schema without creating or modifying any data. Returns validation result with any violations found.", "operationId": "validate_document_schema_v1_collections__collection_identifier__documents_schema_validate_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID or name of the collection.", "title": "Collection Identifier" }, "description": "The ID or name of the collection." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "The document payload to validate against the collection schema.", "title": "Document Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/aggregate": { "post": { "tags": [ "Collection Documents" ], "summary": "Aggregate Documents", "description": "This endpoint performs aggregation operations on documents in a collection.\n\n **Aggregation Framework**: Provides MongoDB-style aggregation operations:\n - GROUP BY: Group documents by one or more fields\n - Aggregations: COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT, etc.\n - Date Operations: Truncate or extract date parts for time-series analysis\n - Filtering: Pre-aggregation filters (WHERE) and post-aggregation filters (HAVING)\n - Sorting & Limiting: Control result ordering and size\n\n **Use Cases**:\n - Count documents by feature type or collection\n - Calculate daily/monthly processing statistics\n - Analyze feature distributions and confidence scores\n - Generate reports with multiple metrics\n\n **Note**: This endpoint works with both MongoDB and Qdrant using the same interface.\n The system automatically selects the appropriate aggregation provider based on\n the underlying metadata store.", "operationId": "aggregate_documents_v1_collections__collection_identifier__documents_aggregate_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the collection.", "title": "Collection Identifier" }, "description": "The unique identifier of the collection." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAggregationRequest", "description": "Aggregation configuration specifying grouping, metrics, and filters." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAggregationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/distinct": { "post": { "tags": [ "Collection Documents" ], "summary": "Return distinct values for a single field.", "description": "Return the set of unique values for one document field across a collection, together with a per-value document count sorted desc. Thin wrapper over `/aggregate` for the common `SELECT DISTINCT ` case \u2014 use this when a UI needs a facet list (e.g. `brand_slug`) without loading every document. Null/missing values are excluded.", "operationId": "distinct_document_values_v1_collections__collection_identifier__documents_distinct_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the collection.", "title": "Collection Identifier" }, "description": "The unique identifier of the collection." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesRequest", "description": "Field + optional filters/limit for the distinct query." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/documents/{document_id}/acl": { "patch": { "tags": [ "Collection Documents" ], "summary": "Update a document's access control list (ACL).", "description": "Update a document's ACL (access control list).\n\nOnly the document owner or an org-scoped key can modify ACL.\nUser-scoped keys that are not the owner will receive a 403.", "operationId": "update_document_acl_v1_collections__collection_identifier__documents__document_id__acl_patch", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the collection.", "title": "Collection Identifier" }, "description": "The ID of the collection." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document.", "title": "Document Id" }, "description": "The ID of the document." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentACLRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/documents/list": { "post": { "tags": [ "Documents" ], "summary": "List documents across all collections (namespace-scoped).", "description": "List documents across all collections in the namespace.\n\nUse this when you don't know which collection a document belongs to,\nor when you need to search across collections. Optionally filter to\nspecific collection_ids.\n\nFor collection-specific listing, use\nPOST /v1/collections/{collection_id}/documents/list instead.", "operationId": "list_documents_ns_v1_documents_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceListDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/documents/batch-get": { "post": { "tags": [ "Documents" ], "summary": "Batch get documents by IDs", "description": "Batch retrieve multiple documents by their IDs.\n\nReturns documents and a list of IDs that were not found.\nMaximum 1000 document IDs per request.", "operationId": "batch_get_documents_v1_documents_batch_get_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchGetDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchGetDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/documents/list/batch": { "post": { "tags": [ "Documents" ], "summary": "Run multiple list-documents queries concurrently.", "description": "Execute up to 10 `POST /v1/documents/list` queries in parallel against the\nsame namespace and return their responses together.\n\nCollapses dossier / multi-collection N+1 fan-outs into one round-trip. Each\nsub-query is independent; a failure in one does not fail the batch \u2014 the\nfailing entry's `response` is null and `error` carries a short message.", "operationId": "list_documents_batch_v1_documents_list_batch_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListDocumentsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/documents/{document_id}": { "get": { "tags": [ "Documents" ], "summary": "Get a document by ID (namespace-scoped).", "description": "Get a document by ID without specifying a collection.\n\nSearches across all collections in the namespace. Use the\ncollection-scoped GET /v1/collections/{collection_id}/documents/{document_id}\nwhen you know the collection for a faster lookup.", "operationId": "get_document_ns_v1_documents__document_id__get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to retrieve.", "title": "Document Id" }, "description": "The ID of the document to retrieve." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage", "default": false, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage" }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Return Vectors" } }, { "name": "return_vector_names", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include a '_vectors' field listing available vector names", "default": false, "title": "Return Vector Names" }, "description": "Include a '_vectors' field listing available vector names" }, { "name": "expand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated fields containing document IDs to resolve inline. Referenced documents are fetched and attached under an '_expanded' key. Supports dot-notation for nested fields (e.g., 'items.product_id'). Max 50 unique references per request.", "title": "Expand" }, "description": "Comma-separated fields containing document IDs to resolve inline. Referenced documents are fetched and attached under an '_expanded' key. Supports dot-notation for nested fields (e.g., 'items.product_id'). Max 50 unique references per request." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Documents" ], "summary": "Partially update a document by ID (namespace-scoped).", "description": "Partially update a document by ID without specifying a collection.\n\nOnly the fields provided are updated; all other fields are left unchanged.", "operationId": "patch_document_ns_v1_documents__document_id__patch", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to patch.", "title": "Document Id" }, "description": "The ID of the document to patch." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDocumentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "put": { "tags": [ "Documents" ], "summary": "Update a document by ID (namespace-scoped).", "description": "Replace a document's fields by ID without specifying a collection.", "operationId": "update_document_ns_v1_documents__document_id__put", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the document to update.", "title": "Document Id" }, "description": "The ID of the document to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_id}/documents/{document_id}/lineage": { "get": { "tags": [ "Document Lineage" ], "summary": "Get document lineage", "description": "Get the complete processing lineage for a document. Shows the full chain of transformations from the root bucket object through all collection processing stages.", "operationId": "get_document_lineage_v1_collections__collection_id__documents__document_id__lineage_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the collection containing the document", "title": "Collection Id" }, "description": "ID of the collection containing the document" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the document to trace", "title": "Document Id" }, "description": "ID of the document to trace" } ], "responses": { "200": { "description": "Document lineage information", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Document Lineage V1 Collections Collection Id Documents Document Id Lineage Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/objects/{object_id}/documents": { "get": { "tags": [ "Document Lineage" ], "summary": "Get all documents derived from an object", "description": "Get all documents created from a specific root object. Useful for finding all processing outputs across multiple collections.", "operationId": "get_documents_by_object_v1_objects__object_id__documents_get", "parameters": [ { "name": "object_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Root object ID to find all derived documents", "title": "Object Id" }, "description": "Root object ID to find all derived documents" }, { "name": "collection_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Optional: Filter to specific collections", "title": "Collection Ids" }, "description": "Optional: Filter to specific collections" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Documents By Object V1 Objects Object Id Documents Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/objects/{object_id}/decomposition-tree": { "get": { "tags": [ "Document Lineage" ], "summary": "Get decomposition tree visualization", "description": "Get a hierarchical tree structure showing all collections and documents derived from a root object. Shows the complete multi-stage processing pipeline.", "operationId": "get_decomposition_tree_v1_objects__object_id__decomposition_tree_get", "parameters": [ { "name": "object_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Root object ID to build decomposition tree for", "title": "Object Id" }, "description": "Root object ID to build decomposition tree for" }, { "name": "include_document_ids", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include full list of document IDs (can be large)", "default": false, "title": "Include Document Ids" }, "description": "Include full list of document IDs (can be large)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Decomposition Tree V1 Objects Object Id Decomposition Tree Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/collections/{collection_identifier}/apply-taxonomy": { "post": { "tags": [ "Collection Taxonomies" ], "summary": "Apply Taxonomy to Existing Documents", "description": "Apply a taxonomy to all existing documents in a collection retroactively.\n\nThis endpoint triggers distributed Ray processing to enrich existing documents\nwith taxonomy data. Unlike automatic materialization (which happens during ingestion),\nthis endpoint allows you to:\n\n1. **Backfill enrichment** for documents ingested before the taxonomy was created\n2. **Re-apply taxonomy** after configuration changes\n3. **Process specific subsets** using scroll_filters\n\n\u2699\ufe0f **Processing Details:**\n- Uses Ray datasets with map_batches for parallel processing\n- Scales horizontally across Ray cluster\n- Non-blocking: Returns immediately with task_id\n- Monitor progress via Tasks API\n\n\u26a0\ufe0f **Prerequisites:**\n- Taxonomy must exist and be valid\n- Taxonomy must be in collection's taxonomy_applications list\n- Collection must contain documents\n\n\ud83d\udcca **Performance:**\n- ~1000-5000 docs/second depending on cluster size\n- Parallel processing across multiple Ray workers\n- Batch size and parallelism configurable\n\n\ud83d\udd0d **Use Cases:**\n- Backfill: Apply new taxonomy to historical data\n- Re-enrichment: Update after taxonomy changes\n- Selective: Process filtered document subsets\n\nSee Collections API and Taxonomies API documentation for details.", "operationId": "apply_taxonomy_to_collection_v1_collections__collection_identifier__apply_taxonomy_post", "parameters": [ { "name": "collection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID or name to apply taxonomy to", "title": "Collection Identifier" }, "description": "Collection ID or name to apply taxonomy to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyTaxonomyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyTaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/stages": { "get": { "tags": [ "Retriever Stages" ], "summary": "List Available Retriever Stages", "description": "List all registered retriever stages with their configurations. Use this endpoint to discover available stages before creating retrievers. Each stage includes its ID, description, category, and full parameter schema. The parameter_schema field contains complete Pydantic JSON Schema with validation rules, descriptions, and examples for all stage parameters.", "operationId": "list_stages_v1_retrievers_stages_get", "responses": { "200": { "description": "List of retriever stage definitions with complete parameter schemas. Each stage includes: - stage_id: Unique identifier to use in retriever configurations - description: Human-readable purpose and behavior - category: Transformation type (filter/sort/reduce/apply) - icon: UI icon identifier - parameter_schema: Full JSON Schema for stage parameters (null if no params)", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RetrieverStageDefinition" }, "type": "array", "title": "Response List Stages V1 Retrievers Stages Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/retrievers/published": { "get": { "tags": [ "Published Retrievers" ], "summary": "List Published Retrievers", "description": "List all published retrievers for the organization.", "operationId": "list_published_retrievers_v1_retrievers_published_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of results", "default": 100, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of results to skip", "default": 0, "title": "Offset" }, "description": "Number of results to skip" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Published Retrievers V1 Retrievers Published Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/publish/stats": { "get": { "tags": [ "Published Retrievers" ], "summary": "Get Organization Publish Stats", "description": "Get organization publish statistics.", "operationId": "get_organization_publish_stats_v1_retrievers_publish_stats_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPublishStatsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/publish": { "post": { "tags": [ "Published Retrievers" ], "summary": "Publish Retriever", "description": "Publish a retriever as a public search interface.\n\nCreates a public API endpoint and branded page for the retriever.\nReturns a public API key that should be stored securely (shown only once).\n\n**Limits:**\n- Maximum 10 published retrievers per organization\n- Public name must be globally unique\n\n**Security:**\n- Public API key is required for all requests\n- Optional password protection via organization secrets\n- Configurable rate limits per retriever\n- Field masking ensures only approved fields are exposed", "operationId": "publish_retriever_v1_retrievers__retriever_id__publish_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever to publish", "title": "Retriever Id" }, "description": "ID of the retriever to publish" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRetrieverRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRetrieverResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Published Retrievers" ], "summary": "Update Published Retriever", "description": "Update published retriever configuration.\n\nAllows updating display config, rate limits, exposed fields, and password protection.\nThe public API key and public name cannot be changed (unpublish and republish instead).", "operationId": "update_published_retriever_v1_retrievers__retriever_id__publish_patch", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever", "title": "Retriever Id" }, "description": "ID of the retriever" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublishedRetrieverRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedRetrieverResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Published Retrievers" ], "summary": "Unpublish Retriever", "description": "Unpublish a retriever.\n\nRemoves the public API endpoint and deletes the short URL redirect.\nThe public API key will immediately stop working.\nThis action cannot be undone (you'll need to republish to get a new API key).", "operationId": "unpublish_retriever_v1_retrievers__retriever_id__publish_delete", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever to unpublish", "title": "Retriever Id" }, "description": "ID of the retriever to unpublish" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Published Retrievers" ], "summary": "Get Published Retriever", "description": "Get published retriever details.\n\nReturns configuration including public URL, display settings, and rate limits.\nThe public API key is not returned (it was shown only once during publishing).\n\nA retriever that simply hasn't been published yet is a normal state (the\nStudio Publish tab opens this on every visit), not an error \u2014 so this\nreturns ``200`` with a ``null`` body rather than ``404``, which previously\nlogged a console error for every unpublished retriever.", "operationId": "get_published_retriever_v1_retrievers__retriever_id__publish_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever", "title": "Retriever Id" }, "description": "ID of the retriever" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PublishedRetrieverResponse" }, { "type": "null" } ], "title": "Response Get Published Retriever V1 Retrievers Retriever Id Publish Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/publish/reconcile": { "post": { "tags": [ "Published Retrievers" ], "summary": "Reconcile Publish State", "description": "Repair published_retrievers <-> marketplace_listings divergence (BACKE-743).\n\nA retriever's public surfaces can drift apart \u2014 e.g. a marketplace listing\nexists but its published_retrievers record is missing, so\n/v1/public/retrievers/{name} 404s (half-published). This detects the state\nand (unless ``dry_run``) repairs it idempotently:\n- missing_published -> create the published record from the listing (reused id)\n- missing_listing -> create the listing from the published record\n- consistent -> ensure cross-link\n- not_published -> no-op", "operationId": "reconcile_publish_state_v1_retrievers__retriever_id__publish_reconcile_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever to reconcile", "title": "Retriever Id" }, "description": "ID of the retriever to reconcile" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Report the divergence state without mutating", "default": false, "title": "Dry Run" }, "description": "Report the divergence state without mutating" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Reconcile Publish State V1 Retrievers Retriever Id Publish Reconcile Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/publish/availability": { "get": { "tags": [ "Published Retrievers" ], "summary": "Check Name Availability", "description": "Check if a public name is available.\n\nPublic names must be globally unique across all organizations.\nUse this endpoint before publishing to ensure your desired name is available.", "operationId": "check_name_availability_v1_retrievers__retriever_id__publish_availability_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the retriever", "title": "Retriever Id" }, "description": "ID of the retriever" }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "description": "Public name to check", "title": "Name" }, "description": "Public name to check" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicNameAvailabilityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/execute": { "post": { "tags": [ "Adhoc Retrievers" ], "summary": "Execute Adhoc Retriever", "description": "Execute a retriever ad-hoc without persisting the configuration.\n\nThis endpoint allows you to execute a retriever without saving it to the database.\nUseful for one-time queries, testing configurations, or temporary searches.\n\nCaching (MI-4726): ad-hoc executions are ALWAYS fresh \u2014 this route never\nreads or writes the execute/stage cache (``cache_status`` is always\n``disabled``), so there is no ``skip_cache`` parameter and none is needed.\nIf you want caching with an explicit opt-out, persist the retriever\n(``POST /retrievers``) and call its ``/retrievers/{id}/execute`` route,\nwhich accepts ``skip_cache`` in both the query string and the body.\n\nStreaming Execution (stream=True):\n Response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream.\n Each stage emits events as it executes, formatted as: data: {json}\\n\\n\n\n Event Types (StreamEventType):\n - stage_start: Emitted when a stage begins (includes stage_name, stage_index, total_stages)\n - stage_complete: Emitted when a stage finishes (includes documents, statistics, budget_used)\n - stage_error: Emitted if a stage fails (includes error message)\n - execution_complete: Final event with complete results and pagination\n - execution_error: Emitted if entire execution fails\n\n StreamStageEvent Fields:\n - event_type: Type of event\n - execution_id: Unique execution identifier\n - stage_name/stage_index/total_stages: Stage progress info\n - documents: Intermediate results (stage_complete only)\n - statistics: Stage metrics (duration_ms, input_count, output_count, efficiency)\n - budget_used: Cumulative consumption (credits_used, time_elapsed_ms, tokens_used)\n\n Response Headers:\n - Content-Type: text/event-stream\n - Cache-Control: no-cache\n - Connection: keep-alive\n - X-Execution-Mode: adhoc\n\nStandard Execution (stream=False, default):\n - Returns ExecuteRetrieverResponse after all stages complete\n - Includes X-Execution-Mode: adhoc header\n - execution_metadata.retriever_persisted = False\n\nUse Cases:\n - One-time queries without saving retriever configuration\n - Testing stage configurations before persisting\n - Dynamic retrieval with varying parameters\n - Real-time progress tracking with streaming", "operationId": "execute_adhoc_retriever_v1_retrievers_execute_post", "parameters": [ { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Return Presigned Urls" } }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Return Vectors" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdhocExecuteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/executions/list": { "post": { "tags": [ "Adhoc Retrievers" ], "summary": "List Adhoc Executions", "description": "List execution history for ad-hoc retrievers.\n\nReturns execution history for all ad-hoc retriever executions in the namespace,\nsorted by timestamp descending (most recent first).\n\nUse Cases:\n - Track ad-hoc retriever usage across the namespace\n - Debug ad-hoc retriever executions\n - Analyze query patterns from ad-hoc searches\n - Monitor performance of ad-hoc executions\n\nFiltering:\n - Filter by status (completed, failed, etc.)\n - Filter by time range (start_time, end_time)\n\nPagination:\n - Supports offset-based pagination via query parameters\n - Default limit: 20, max limit: 100\n - Use ?page_size=X&page_number=Y for pagination", "operationId": "list_adhoc_executions_v1_retrievers_executions_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdhocExecutionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdhocExecutionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/executions/{execution_id}": { "get": { "tags": [ "Adhoc Retrievers" ], "summary": "Get Adhoc Execution", "description": "Get detailed execution information for a specific ad-hoc retriever execution.\n\nReturns comprehensive execution details including:\n - Execution metadata (status, duration, credits used)\n - Performance metrics (documents processed/returned, cache hit rate)\n - Input data and query summary\n - Stage completion information\n - Collections queried\n\nUse Cases:\n - Debug specific ad-hoc executions\n - Analyze performance of a particular query\n - Retrieve execution inputs for reproduction\n - Audit ad-hoc retriever usage\n\nRaises:\n 404 NotFoundError: If execution not found or not an ad-hoc execution", "operationId": "get_adhoc_execution_v1_retrievers_executions__execution_id__get", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Execution identifier.", "title": "Execution Id" }, "description": "Execution identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdhocExecutionDetail" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/weights": { "get": { "tags": [ "Retriever Learned Fusion" ], "summary": "Get Weights", "description": "Get global learned fusion weight distribution for a retriever.", "operationId": "get_weights_v1_retrievers__retriever_id__learned_fusion_weights_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeightsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/weights/{user_id}": { "get": { "tags": [ "Retriever Learned Fusion" ], "summary": "Get User Weights", "description": "Get per-user learned fusion weights for a retriever.", "operationId": "get_user_weights_v1_retrievers__retriever_id__learned_fusion_weights__user_id__get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWeightsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/stats": { "get": { "tags": [ "Retriever Learned Fusion" ], "summary": "Get Stats", "description": "Get aggregate statistics for a retriever's learned fusion system.", "operationId": "get_stats_v1_retrievers__retriever_id__learned_fusion_stats_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearnedFusionStatsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/activity": { "get": { "tags": [ "Retriever Learned Fusion" ], "summary": "Get Activity", "description": "Get recent learned fusion activity events.", "operationId": "get_activity_v1_retrievers__retriever_id__learned_fusion_activity_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/disable": { "post": { "tags": [ "Retriever Learned Fusion" ], "summary": "Disable Learned Fusion", "description": "Disable learned fusion for a retriever (kill switch).", "operationId": "disable_learned_fusion_v1_retrievers__retriever_id__learned_fusion_disable_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Disable Learned Fusion V1 Retrievers Retriever Id Learned Fusion Disable Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/enable": { "post": { "tags": [ "Retriever Learned Fusion" ], "summary": "Enable Learned Fusion", "description": "Enable learned fusion for a retriever.", "operationId": "enable_learned_fusion_v1_retrievers__retriever_id__learned_fusion_enable_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Enable Learned Fusion V1 Retrievers Retriever Id Learned Fusion Enable Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/rollout": { "post": { "tags": [ "Retriever Learned Fusion" ], "summary": "Set Rollout", "description": "Set a live traffic-split override (the Studio rollout slider).\n\nTakes effect immediately for new requests without editing the retriever\nconfig. Setting 100 clears the override.", "operationId": "set_rollout_v1_retrievers__retriever_id__learned_fusion_rollout_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRolloutRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Set Rollout V1 Retrievers Retriever Id Learned Fusion Rollout Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/opt-out/{user_id}": { "post": { "tags": [ "Retriever Learned Fusion" ], "summary": "Opt Out User", "description": "Opt a user out of learned fusion personalization.", "operationId": "opt_out_user_v1_retrievers__retriever_id__learned_fusion_opt_out__user_id__post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Opt Out User V1 Retrievers Retriever Id Learned Fusion Opt Out User Id Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/opt-in/{user_id}": { "post": { "tags": [ "Retriever Learned Fusion" ], "summary": "Opt In User", "description": "Opt a user back into learned fusion personalization.", "operationId": "opt_in_user_v1_retrievers__retriever_id__learned_fusion_opt_in__user_id__post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Opt In User V1 Retrievers Retriever Id Learned Fusion Opt In User Id Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/learned-fusion/user/{user_id}": { "delete": { "tags": [ "Retriever Learned Fusion" ], "summary": "Reset User", "description": "Reset a user's learned fusion state (inserts a reset marker).", "operationId": "reset_user_v1_retrievers__retriever_id__learned_fusion_user__user_id__delete", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Reset User V1 Retrievers Retriever Id Learned Fusion User User Id Delete" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/benchmarks": { "post": { "tags": [ "Retriever Benchmarks" ], "summary": "Create benchmark", "description": "Create a new benchmark run to compare retriever pipelines. The benchmark will replay historical sessions and measure alignment with observed user behavior.", "operationId": "create_benchmark_v1_retrievers_benchmarks_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBenchmarkRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Retriever Benchmarks" ], "summary": "List benchmarks", "description": "List benchmarks with optional filtering", "operationId": "list_benchmarks_v1_retrievers_benchmarks_get", "parameters": [ { "name": "retriever_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to benchmarks involving this retriever (as baseline or candidate)", "title": "Retriever Id" }, "description": "Filter to benchmarks involving this retriever (as baseline or candidate)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status (pending, building_sessions, replaying, completed, failed)", "title": "Status" }, "description": "Filter by status (pending, building_sessions, replaying, completed, failed)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number", "default": 1, "title": "Page" }, "description": "Page number" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Items per page", "default": 20, "title": "Page Size" }, "description": "Items per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/benchmarks/{benchmark_id}": { "get": { "tags": [ "Retriever Benchmarks" ], "summary": "Get benchmark", "description": "Get benchmark status and results by ID", "operationId": "get_benchmark_v1_retrievers_benchmarks__benchmark_id__get", "parameters": [ { "name": "benchmark_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Benchmark Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Retriever Benchmarks" ], "summary": "Delete benchmark", "description": "Delete a benchmark and its results", "operationId": "delete_benchmark_v1_retrievers_benchmarks__benchmark_id__delete", "parameters": [ { "name": "benchmark_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Benchmark Id" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers": { "post": { "tags": [ "Retrievers" ], "summary": "Create Retriever", "description": "Create a new retriever.\n\nA retriever executes a series of stages to find and process documents\nfrom one or more collections.", "operationId": "create_retriever_v1_retrievers_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetrieverRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverConfig" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Retrievers" ], "summary": "List Retrievers Get", "description": "List all retrievers in the namespace (GET alias for POST /list).", "operationId": "list_retrievers_get_v1_retrievers_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRetrieversResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/list": { "post": { "tags": [ "Retrievers" ], "summary": "List Retrievers", "description": "List all retrievers in the namespace.", "operationId": "list_retrievers_v1_retrievers_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRetrieversRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRetrieversResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}": { "get": { "tags": [ "Retrievers" ], "summary": "Get Retriever", "description": "Get a retriever by ID or name.", "operationId": "get_retriever_v1_retrievers__retriever_id__get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverModel-Output" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Retrievers" ], "summary": "Patch Retriever", "description": "Update a retriever's metadata.\n\nEditable fields:\n- name, description, tags, display_config: metadata\n- collection_identifiers: re-points + re-validates stage feature URIs\n- stages (BACKE-1287): edit stages in place on an UNPUBLISHED retriever\n (change a filter/operator/rerank without clone+repoint+delete); the full\n stage list is replaced + re-validated as on create. A PUBLISHED retriever's\n stages stay immutable \u2014 clone or unpublish to change them.\n\ninput_schema and budget_limits remain immutable; use POST /{retriever_id}/clone.", "operationId": "patch_retriever_v1_retrievers__retriever_id__patch", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRetrieverRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRetrieverResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Retrievers" ], "summary": "Delete Retriever", "description": "Delete a retriever and all its resources comprehensively.\n\nDeletes:\n- Published retrievers\n- Execution history\n- Interactions (user feedback)\n- Evaluations\n- Cache entries\n- Retriever metadata\n\nThe deletion is performed synchronously and returns when complete.", "operationId": "delete_retriever_v1_retrievers__retriever_id__delete", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/clone": { "post": { "tags": [ "Retrievers" ], "summary": "Clone Retriever", "description": "Clone a retriever with optional modifications.\n\n**Purpose:**\nCreates a NEW retriever (with new ID) based on an existing one. This is the\nrecommended way to iterate on retriever designs when you need to modify core\nlogic that PATCH doesn't allow (stages, input_schema, collections).\n\n**Clone vs PATCH vs Template:**\n- **PATCH**: Update metadata only (name, description, tags, display_config)\n- **Clone**: Copy and modify core logic (stages, input_schema, collections)\n- **Template**: Start from a pre-configured pattern (for new projects)\n\n**Common Use Cases:**\n- Fix a typo in a stage name\n- Add or remove stages\n- Change target collections\n- Create variants (e.g., \"strict\" vs \"relaxed\" versions)\n- Test modifications before replacing production retriever\n\n**How it works:**\n1. Source retriever is copied\n2. You provide a new name (REQUIRED)\n3. Optionally override any other fields\n4. A new retriever is created with a new ID\n5. Original retriever remains unchanged\n\n**All fields except retriever_name are OPTIONAL:**\n- Omit a field to copy from source\n- Provide a field to override the source value", "operationId": "clone_retriever_v1_retrievers__retriever_id__clone_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Source retriever ID or name to clone.", "title": "Retriever Id" }, "description": "Source retriever ID or name to clone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneRetrieverRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneRetrieverResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/execute": { "post": { "tags": [ "Retrievers" ], "summary": "Execute Retriever (Auto-Optimized)", "description": "Execute a retriever and return matching documents. The pipeline is automatically optimized before execution for best performance.\n\n**Automatic Optimization:**\nYour pipeline stages are automatically transformed for optimal performance:\n- Filters pushed down to reduce expensive operations\n- Redundant stages merged or eliminated\n- Grouping operations pushed to database layer (10-100x faster)\n- Operations reordered for efficiency\n\n**Streaming Support:**\nSet stream=true in the request body to receive real-time stage updates via SSE:\n- Response uses text/event-stream content type\n- Each stage emits stage_start and stage_complete events\n- Final event contains complete results and pagination\n- Useful for progress tracking and debugging\n\n**Response Includes (when stream=false):**\n- documents: Final matching documents\n- pagination: Pagination metadata\n- stage_statistics: Per-stage execution metrics\n- budget: Credit/time consumption\n- optimization_applied: Whether optimizations were applied\n- optimization_summary: Details about transformations (when applied)\n\n**Optimization Summary Example:**\n```json\n{\n \"optimization_applied\": true,\n \"optimization_summary\": {\n \"original_stage_count\": 5,\n \"optimized_stage_count\": 3,\n \"optimization_time_ms\": 8.2,\n \"rules_applied\": [\"push_down_filters\", \"group_by_push_down\"],\n \"stage_reduction_pct\": 40.0\n }\n}\n```\n\nUse the /explain endpoint to see the optimized execution plan before running.", "operationId": "execute_retriever_v1_retrievers__retriever_id__execute_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name. Pipeline will be automatically optimized before execution.", "title": "Retriever Id" }, "description": "Retriever ID or name. Pipeline will be automatically optimized before execution." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either source is true, presigning is enabled.", "default": false, "title": "Return Presigned Urls" }, "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either source is true, presigning is enabled." }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include vector embeddings in result documents. Also accepted as a body field \u2014 if either source is true, vectors are returned.", "default": false, "title": "Return Vectors" }, "description": "Include vector embeddings in result documents. Also accepted as a body field \u2014 if either source is true, vectors are returned." }, { "name": "explain", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return the inline `explain_plan` (per-stage timings + optimization summary) in the response. Also accepted as a body field \u2014 if either source is true, the plan is included.", "default": false, "title": "Explain" }, "description": "Return the inline `explain_plan` (per-stage timings + optimization summary) in the response. Also accepted as a body field \u2014 if either source is true, the plan is included." }, { "name": "include_legacy_results", "in": "query", "required": false, "schema": { "type": "boolean", "description": "DEPRECATED. Restore the legacy `results` alias (a byte-for-byte copy of `documents`). Off by default \u2014 `results` previously duplicated the entire document array in every response (~half the payload). Prefer `documents`; use this only as a temporary migration shim.", "default": false, "title": "Include Legacy Results" }, "description": "DEPRECATED. Restore the legacy `results` alias (a byte-for-byte copy of `documents`). Off by default \u2014 `results` previously duplicated the entire document array in every response (~half the payload). Prefer `documents`; use this only as a temporary migration shim." }, { "name": "skip_cache", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the execute/stage cache read for this request (a fresh execution; the result is still written to cache). Also accepted as a body field \u2014 if either source is true, the cache is skipped.", "default": false, "title": "Skip Cache" }, "description": "Bypass the execute/stage cache read for this request (a fresh execution; the result is still written to cache). Also accepted as a body field \u2014 if either source is true, the cache is skipped." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRetrieverRequest", "description": "Execution request with inputs, filters, pagination, and optional stream parameter. Set stream=true to receive real-time stage updates via Server-Sent Events." } } } }, "responses": { "200": { "description": "Execution results with documents, pagination, statistics, and optimization details. When stream=true, returns Server-Sent Events. When stream=false, returns JSON response.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/execute/batch": { "post": { "tags": [ "Retrievers" ], "summary": "Batch Execute Retriever", "description": "Execute a retriever against multiple queries in a single request. The retriever is fetched and optimized once, then executed concurrently against each query with bounded parallelism.\n\n**Use case:** IP safety / copyright clearance \u2014 scan 20 media files against face, logo, or audio retrievers in one call instead of 60 sequential SSE requests.\n\n**Limits:** 1-50 queries per batch, 1-20 concurrency.\n\nReturns results keyed by query index with per-query documents and errors.", "operationId": "execute_batch_v1_retrievers__retriever_id__execute_batch_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either source is true, presigning is enabled.", "default": false, "title": "Return Presigned Urls" }, "description": "Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field \u2014 if either source is true, presigning is enabled." }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include vector embeddings in result documents. Also accepted as a body field \u2014 if either source is true, vectors are returned.", "default": false, "title": "Return Vectors" }, "description": "Include vector embeddings in result documents. Also accepted as a body field \u2014 if either source is true, vectors are returned." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteBatchRequest", "description": "Batch of queries to execute." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/executions/list": { "post": { "tags": [ "Retrievers" ], "summary": "List Executions", "description": "List execution history for a retriever.", "operationId": "list_executions_v1_retrievers__retriever_id__executions_list_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListExecutionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListExecutionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/executions/{execution_id}/status": { "get": { "tags": [ "Retrievers" ], "summary": "Get Live Execution Status", "description": "Fetch live execution status from the durability journal. Returns real-time progress including current stage, completed stages, and heartbeat timestamp. If the execution is completed, returns the full results. Falls back to ClickHouse for historical executions.", "operationId": "get_execution_status_v1_retrievers__retriever_id__executions__execution_id__status_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Execution identifier.", "title": "Execution Id" }, "description": "Execution identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Execution Status V1 Retrievers Retriever Id Executions Execution Id Status Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/executions/{execution_id}": { "get": { "tags": [ "Retrievers" ], "summary": "Get Execution", "description": "Get execution details and statistics.", "operationId": "get_execution_v1_retrievers__retriever_id__executions__execution_id__get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Execution identifier.", "title": "Execution Id" }, "description": "Execution identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionDetail" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/executions/{execution_id}/profile": { "get": { "tags": [ "Retrievers" ], "summary": "Get Execution Query Profile (explain-on-execute read path)", "description": "Return the query profile for a PAST execution, by execution_id \u2014 the same plan that `explain=true` returns inline at execute time, read back later. Contains per-stage timings + input/output counts, MVS execution stats, the optimizer summary, and (as it is wired) the shard ExecutionTrace (chosen legs, fusion, push-downs, nprobe, served/shadow planner). Reads the query_profile persisted on the RETRIEVER_EXECUTION analytics event (latest row wins). Returns 404 if the execution has no captured profile. This is the queryable, Studio-friendly counterpart to inline explain.", "operationId": "get_execution_profile_v1_retrievers__retriever_id__executions__execution_id__profile_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name.", "title": "Retriever Id" }, "description": "Retriever ID or name." }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Execution identifier.", "title": "Execution Id" }, "description": "Execution identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Execution Profile V1 Retrievers Retriever Id Executions Execution Id Profile Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/execute/explain": { "post": { "tags": [ "Retrievers" ], "summary": "Explain Retriever Execution Plan", "description": "Get a detailed execution plan for a retriever without actually executing it. Similar to MongoDB's explain plan or SQL's EXPLAIN command, this endpoint helps you understand performance characteristics, identify bottlenecks, estimate costs, and troubleshoot retrieval issues before running expensive queries.\n\n**What This Returns:**\n- Stage-by-stage execution plan (AFTER automatic optimizations)\n- Estimated costs (credits + time per stage)\n- Document flow projections (input/output counts per stage)\n- Efficiency metrics (selectivity ratios, cache likelihood)\n- Bottleneck identification (slowest/most expensive stages)\n- Optimization details (transformations applied by the optimizer)\n- Performance warnings and improvement suggestions\n\n\n**Key Features:**\n- **Cost Estimation**: See how many credits and milliseconds each stage will consume\n- **Bottleneck Detection**: Identify which stages dominate execution time\n- **Optimization Transparency**: Understand how your pipeline was optimized\n- **Cache Analysis**: See which stages are likely to hit cache\n- **Accuracy Troubleshooting**: Analyze stage efficiency and document flow\n- **Latency Analysis**: Break down estimated duration by stage\n\n\n**Important:** The execution_plan shows OPTIMIZED stages (after automatic transformations like filter push-down, stage fusion, and grouping optimization). Check optimization_details to understand what changed from your original configuration.\n\n\n**Use Cases:**\n- Debug slow retrievers by identifying bottleneck stages\n- Estimate costs before running expensive queries\n- Understand how the optimizer transformed your pipeline\n- Troubleshoot accuracy issues by analyzing stage selectivity\n- Compare different retriever configurations\n- Plan budget allocation for production workloads\n\n\n**Example Response:**\n```json\n{\n \"retriever_id\": \"ret_abc123\",\n \"retriever_name\": \"product_search\",\n \"execution_plan\": [\n {\n \"stage_index\": 0,\n \"stage_name\": \"attribute_filter\",\n \"stage_type\": \"filter\",\n \"estimated_input\": 10000,\n \"estimated_output\": 5000,\n \"estimated_efficiency\": 0.5,\n \"estimated_cost_credits\": 0.01,\n \"estimated_duration_ms\": 20,\n \"cache_likely\": true,\n \"optimization_notes\": [\"Pushed down from stage 2\"],\n \"warnings\": []\n },\n {\n \"stage_index\": 1,\n \"stage_name\": \"semantic_search\",\n \"stage_type\": \"filter\",\n \"estimated_input\": 5000,\n \"estimated_output\": 100,\n \"estimated_efficiency\": 0.02,\n \"estimated_cost_credits\": 0.5,\n \"estimated_duration_ms\": 200,\n \"cache_likely\": false,\n \"optimization_notes\": [],\n \"warnings\": [\"High cost stage - consider reducing limit\"]\n }\n ],\n \"estimated_cost\": {\n \"total_credits\": 0.51,\n \"total_duration_ms\": 220\n },\n \"bottleneck_stages\": [\"semantic_search\"],\n \"optimization_applied\": true,\n \"optimization_details\": {\n \"original_stage_count\": 3,\n \"optimized_stage_count\": 2,\n \"optimization_time_ms\": 8.2,\n \"stage_reduction_pct\": 33.3,\n \"decisions\": [\n {\n \"rule_type\": \"push_down_filters\",\n \"applied\": true,\n \"reason\": \"Moved attribute_filter before semantic_search to reduce search scope\"\n }\n ]\n },\n \"optimization_suggestions\": [\n {\n \"type\": \"reduce_limit\",\n \"stage\": \"semantic_search\",\n \"message\": \"Consider reducing limit to improve latency\"\n }\n ]\n}\n```", "operationId": "explain_retriever_execution_v1_retrievers__retriever_id__execute_explain_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID or name to explain. The execution plan will show the OPTIMIZED version after automatic transformations.", "title": "Retriever Id" }, "description": "Retriever ID or name to explain. The execution plan will show the OPTIMIZED version after automatic transformations." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainRetrieverRequest", "description": "Optional hypothetical inputs for estimation. Provide sample inputs to see how the plan changes with different parameters (e.g., different top_k values, query complexity, filter combinations). If not provided, uses default/representative values." } } } }, "responses": { "200": { "description": "Detailed execution plan with stage-by-stage cost estimates, optimization details, bottleneck identification, and performance insights. Use this to troubleshoot slow queries, estimate costs, and understand optimizer transformations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainRetrieverResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/api-keys": { "post": { "tags": [ "Retriever API Keys" ], "summary": "Create Retriever API Key", "description": "Generate a scoped API key for executing this specific retriever.\n\n **Use Cases:**\n - Provide external services with execution-only access\n - Embed retriever calls in customer applications\n - Create separate keys for staging vs production\n - Implement per-customer access keys for SaaS products\n\n **Security:**\n - Keys grant EXECUTE_RETRIEVER permission only\n - Keys are scoped to single retriever (cannot access others)\n - Keys inherit org's rate limits\n - Keys can be revoked instantly\n - Key prefix (ret_sk_abc...) shown in UI for identification\n\n **Ownership:**\n - Only the organization that owns the retriever can create keys\n - Verified by matching internal_id + namespace_id\n\n **Key Format:**\n - Prefix: ret_sk_\n - Length: 60 characters\n - Example: ret_sk_abcdefghijklmnopqrstuvwxyz123456789...\n\n **Response:**\n - Plaintext key shown ONLY ONCE in response\n - Save the key immediately - it cannot be retrieved later\n - Key prefix stored for identification in UI", "operationId": "create_retriever_api_key_v1_retrievers__retriever_id__api_keys_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetrieverAPIKeyRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverAPIKeyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Retriever API Keys" ], "summary": "List Retriever API Keys", "description": "List all API keys for this retriever.\n\n **Fields:**\n - key_id: Public identifier for the key\n - key_prefix: First 10 characters + \"...\" for identification (e.g., \"ret_sk_abc...\")\n - name: Human-friendly label\n - created_at: When the key was created\n - last_used_at: When the key was last used (if ever)\n - status: ACTIVE, REVOKED, or EXPIRED\n - expires_at: Expiration timestamp (if set)\n\n **Note:**\n - Plaintext key is NEVER returned in list responses\n - Only shown once in creation response\n - Use key_prefix to identify keys in the UI", "operationId": "list_retriever_api_keys_v1_retrievers__retriever_id__api_keys_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "include_revoked", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include revoked and expired keys in the response", "default": false, "title": "Include Revoked" }, "description": "Include revoked and expired keys in the response" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverAPIKeyListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/api-keys/{key_id}": { "delete": { "tags": [ "Retriever API Keys" ], "summary": "Revoke Retriever API Key", "description": "Revoke a retriever-scoped API key.\n\n **Effect:**\n - Key status is set to REVOKED\n - Key can no longer be used for authentication\n - Revocation is immediate (no grace period)\n - Auth cache is invalidated immediately\n - Cannot be undone (create a new key if needed)\n\n **Audit:**\n - Revocation is logged in the retriever's audit trail\n - Includes actor user ID and timestamp", "operationId": "revoke_retriever_api_key_v1_retrievers__retriever_id__api_keys__key_id__delete", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/interactions": { "post": { "tags": [ "Retriever Interactions" ], "summary": "Create Interaction", "description": "Record a search interaction (view, click, feedback, etc.).\n\nAutomatically computes and injects ``metadata.reward_value`` based on\nthe interaction types and the retriever's reward_map configuration.\nThis pre-computed value is used by the learned-fusion bandit aggregation\nquery so it doesn't need to join against the retriever config at read time.\n\n**Deduplication (Phase 4e):** If ``(execution_id, feature_id,\ninteraction_type)`` has already been recorded within the last 5 minutes\nthe duplicate is silently dropped.\n\n**Session cache (Phase 1b):** When ``session_id`` is present the\ninteraction is also written to the Redis session cache so the Thompson\nSampling bandit can incorporate it in real time (before ClickHouse\nwrite-then-read latency settles).", "operationId": "create_interaction_v1_retrievers_interactions_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInteraction" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/interactions/batch": { "post": { "tags": [ "Retriever Interactions" ], "summary": "Create Interactions Bulk", "description": "Record up to 1000 interactions in one call \u2014 for backfilling history.\n\nEach interaction is enriched (reward_value, feature_uri/context promotion)\nexactly like the single-create path, then written. Reward config is resolved\nONCE per distinct retriever (not per interaction). Dedup and the real-time\nsession cache are skipped \u2014 bulk writes are for historical backfill, not\nlive in-session adaptation. Set each interaction's ``occurred_at`` to its\ntrue timestamp so temporal decay weights it by real age.", "operationId": "create_interactions_bulk_v1_retrievers_interactions_batch_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInteractionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInteractionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/interactions/list": { "post": { "tags": [ "Retriever Interactions" ], "summary": "List Interactions", "description": "List interactions with optional filters and pagination.\n\nSupports hybrid filtering: simple fields + advanced LogicalOperator.", "operationId": "list_interactions_v1_retrievers_interactions_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInteractionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInteractionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/interactions/{interaction_id}": { "get": { "tags": [ "Retriever Interactions" ], "summary": "Get Interaction", "description": "Get a specific interaction.", "operationId": "get_interaction_v1_retrievers_interactions__interaction_id__get", "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Interaction Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Retriever Interactions" ], "summary": "Delete Interaction", "description": "Delete a specific interaction (idempotent - succeeds even if already deleted).", "operationId": "delete_interaction_v1_retrievers_interactions__interaction_id__delete", "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Interaction Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Interaction V1 Retrievers Interactions Interaction Id Delete" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/evaluations/datasets": { "post": { "tags": [ "Retriever Evaluations" ], "summary": "Create evaluation dataset", "description": "Create a ground truth dataset for evaluating retrievers. Include queries with their relevant documents and optional graded relevance scores.", "operationId": "create_dataset_v1_retrievers_evaluations_datasets_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDataset" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Retriever Evaluations" ], "summary": "List evaluation datasets", "description": "List all evaluation datasets with pagination", "operationId": "list_datasets_v1_retrievers_evaluations_datasets_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Items per page", "default": 20, "title": "Page Size" }, "description": "Items per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/evaluations/datasets/{dataset_identifier}": { "get": { "tags": [ "Retriever Evaluations" ], "summary": "Get evaluation dataset", "description": "Retrieve a specific dataset by ID or name", "operationId": "get_dataset_v1_retrievers_evaluations_datasets__dataset_identifier__get", "parameters": [ { "name": "dataset_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Dataset Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDataset" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/evaluations/generate-from-interactions": { "post": { "tags": [ "Retriever Evaluations" ], "summary": "Generate evaluation dataset from interactions", "description": "Auto-generate a ground truth evaluation dataset by mining user interactions for this retriever. Queries with sufficient positive interactions (click, purchase, bookmark, etc.) are used to infer relevance labels, creating a dataset suitable for offline evaluation.", "operationId": "generate_dataset_from_interactions_v1_retrievers__retriever_id__evaluations_generate_from_interactions_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFromInteractionsRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDataset" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/evaluations": { "post": { "tags": [ "Retriever Evaluations" ], "summary": "Run evaluation", "description": "Evaluate a retriever's quality using a ground truth dataset. Returns immediately with a task ID - evaluation runs asynchronously.", "operationId": "start_evaluation_v1_retrievers__retriever_id__evaluations_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartEvaluationRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartEvaluationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Retriever Evaluations" ], "summary": "List evaluations", "description": "List all evaluations for a retriever with optional filters", "operationId": "list_evaluations_v1_retrievers__retriever_id__evaluations_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/EvaluationStatus" }, { "type": "null" } ], "description": "Filter by status (pending, in_progress, completed, failed)", "title": "Status" }, "description": "Filter by status (pending, in_progress, completed, failed)" }, { "name": "dataset_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by dataset name", "title": "Dataset Name" }, "description": "Filter by dataset name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Items per page", "default": 20, "title": "Page Size" }, "description": "Items per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/retrievers/{retriever_id}/evaluations/{evaluation_id}": { "get": { "tags": [ "Retriever Evaluations" ], "summary": "Get evaluation results", "description": "Retrieve evaluation results with all calculated metrics", "operationId": "get_evaluation_v1_retrievers__retriever_id__evaluations__evaluation_id__get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "evaluation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Evaluation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRecord" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/evaluations": { "get": { "tags": [ "Retriever Evaluations" ], "summary": "Discover evaluation endpoints", "description": "Lightweight discovery endpoint. Evaluation **datasets** are namespace-scoped and evaluation **runs** are retriever-scoped, so both live under `/v1/retrievers/...` rather than a top-level `/v1/evaluations/{id}`. This endpoint exists so a bare `GET /v1/evaluations` returns the real endpoint map instead of a hintless 404.", "operationId": "discover_evaluations_v1_evaluations_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Discover Evaluations V1 Evaluations Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/inference": { "post": { "tags": [ "Inference" ], "summary": "Execute Raw Inference", "description": "Execute raw inference with provider+model or custom plugin.\n\nThis endpoint provides direct access to inference services without\nthe retriever framework overhead. Supports two modes:\n\n1. **Provider + Model**: Use standard providers (openai, google, anthropic)\n2. **Custom Plugin**: Use your custom inference plugins by inference_name\n\n## Supported Providers\n\n- **openai**: GPT models, embeddings, Whisper transcription\n- **google**: Gemini models, Vertex multimodal embeddings (1408D)\n- **anthropic**: Claude models\n\n## Examples\n\n### Custom Plugin (by inference_name)\n```json\n{\n \"inference_name\": \"my_text_embedder_1_0_0\",\n \"inputs\": {\"text\": \"hello world\"},\n \"parameters\": {}\n}\n```\n\n### Custom Plugin (by feature_uri)\n```json\n{\n \"feature_uri\": \"mixpeek://my_custom_embedder@1.0.0/embedding\",\n \"inputs\": {\"text\": \"hello world\"},\n \"parameters\": {}\n}\n```\n\n### Builtin Embedder (by feature_uri)\n```json\n{\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"inputs\": {\"text\": \"hello world\"},\n \"parameters\": {}\n}\n```\n\n### Chat Completion\n```json\n{\n \"provider\": \"openai\",\n \"model\": \"gpt-4o-mini\",\n \"inputs\": {\"prompts\": [\"What is AI?\"]},\n \"parameters\": {\"temperature\": 0.7, \"max_tokens\": 500}\n}\n```\n\n### Text Embedding (OpenAI)\n```json\n{\n \"provider\": \"openai\",\n \"model\": \"text-embedding-3-large\",\n \"inputs\": {\"text\": \"machine learning\"},\n \"parameters\": {}\n}\n```\n\n### Text Embedding (Google Vertex Multimodal - 1408D)\n```json\n{\n \"provider\": \"google\",\n \"model\": \"multimodalembedding\",\n \"inputs\": {\"text\": \"machine learning\"},\n \"parameters\": {}\n}\n```\n\n### Image Embedding (Google Vertex Multimodal - 1408D)\n```json\n{\n \"provider\": \"google\",\n \"model\": \"multimodalembedding\",\n \"inputs\": {\"image_url\": \"https://example.com/image.jpg\"},\n \"parameters\": {}\n}\n```\n\n### Image Embedding from Base64\n```json\n{\n \"provider\": \"google\",\n \"model\": \"multimodalembedding\",\n \"inputs\": {\"image_base64\": \"\"},\n \"parameters\": {}\n}\n```\n\n### Video Embedding (Google Vertex Multimodal - 1408D)\n```json\n{\n \"provider\": \"google\",\n \"model\": \"multimodalembedding\",\n \"inputs\": {\"video_url\": \"https://example.com/video.mp4\"},\n \"parameters\": {}\n}\n```\n\n### Video Embedding from Base64\n```json\n{\n \"provider\": \"google\",\n \"model\": \"multimodalembedding\",\n \"inputs\": {\"video_base64\": \"\"},\n \"parameters\": {}\n}\n```\n\n### Audio Transcription\n```json\n{\n \"provider\": \"openai\",\n \"model\": \"whisper-1\",\n \"inputs\": {\"audio_url\": \"https://example.com/audio.mp3\"},\n \"parameters\": {}\n}\n```\n\n### Vision (Multimodal LLM)\n```json\n{\n \"provider\": \"openai\",\n \"model\": \"gpt-4o\",\n \"inputs\": {\n \"prompts\": [\"Describe this image\"],\n \"image_url\": \"https://example.com/image.jpg\"\n },\n \"parameters\": {\"temperature\": 0.5}\n}\n```\n\nArgs:\n request: FastAPI request object (populated by middleware)\n payload: Raw inference request\n\nReturns:\n Inference response with results and metadata\n\nRaises:\n 400 Bad Request: Invalid provider, model, or inputs\n 401 Unauthorized: Missing or invalid API key\n 429 Too Many Requests: Rate limit exceeded\n 500 Internal Server Error: Inference execution failed", "operationId": "execute_raw_inference_v1_inference_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawInferenceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawInferenceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "Get Organization", "description": "Get current organization details.\n\nSecurity: Infrastructure configuration is NOT exposed via this endpoint.\nInfrastructure (Qdrant URLs, Ray clusters) is only accessible via private admin endpoints.", "operationId": "get_organization_v1_organizations_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationModelResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Organizations" ], "summary": "Update Organization", "description": "Update organization settings (requires ADMIN permission).\n\nSecurity: Infrastructure configuration cannot be modified via this endpoint.\nInfrastructure updates require Mixpeek admin access via private endpoints.", "operationId": "update_organization_v1_organizations_patch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationModelResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/credits": { "get": { "tags": [ "Organizations" ], "summary": "Get Credits", "description": "Read the org's credit/usage state.\n\nBACKE-2759(2): GET on this path returned 405 (only POST existed) \u2014 a\nnatural read that every evaluator tries. Returns the ENFORCED ceiling\n(`effective_monthly_credit_cap`, the number the block point uses), the\ncurrent month usage, and the decorative legacy `credit_count` clearly\nlabeled as non-gating.", "operationId": "get_credits_v1_organizations_credits_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Credits V1 Organizations Credits Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Organizations" ], "summary": "Add Credits", "description": "Add credits to the organization.\n\nWhen credits are added to a FREE-tier organization:\n- If new balance >= 100,000: Auto-upgrade to PRO tier\n- If new balance >= 1,000,000: Auto-upgrade to TEAM tier\n\nPRO and TEAM tiers get enhanced rate limits automatically.", "operationId": "add_credits_v1_organizations_credits_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCreditsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCreditsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/me": { "get": { "tags": [ "Account" ], "summary": "Whoami", "description": "Return the caller's identity: organization, tier, key metadata, limits.\n\nWorks for every valid key. `/account` is an undocumented alias so both\nnatural spellings resolve.", "operationId": "whoami_v1_me_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections": { "post": { "tags": [ "Organization Connections" ], "summary": "Create Storage Connection", "description": "Create a new storage provider connection.\n\nEstablishes a connection to an external storage provider (Google Drive, S3, etc.)\nfor use in sync operations. Credentials are validated before saving unless\ntest_before_save is False.\n\n**Use Cases:**\n- Connect to team Google Drive for automated file ingestion\n- Link customer S3 buckets for batch processing\n- Set up storage connections for sync operations\n\n**Security:**\n- Requires ADMIN permission\n- Credentials are encrypted at rest\n- Connection is tested before saving (unless test_before_save=False)\n- Audit log entry created for compliance\n\n**Example:**\n```bash\ncurl -X POST \"http://localhost:8000/v1/organizations/connections\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Marketing Drive\",\n \"provider_type\": \"google_drive\",\n \"provider_config\": {\n \"credentials\": {...},\n \"shared_drive_id\": \"0AH-Xabc123\"\n }\n }'\n```", "operationId": "create_storage_connection_v1_organizations_connections_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections/list": { "post": { "tags": [ "Organization Connections" ], "summary": "List Storage Connections", "description": "List storage connections for the authenticated organization.\n\nReturns paginated results with optional filters for provider type, status,\nand active flag. Results are sorted by creation date (newest first).\n\n**Use Cases:**\n- List all active Google Drive connections\n- Find failed connections that need attention\n- Filter by provider type for sync configuration\n\n**Example:**\n```bash\ncurl -X POST \"http://localhost:8000/v1/organizations/connections/list\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"provider_type\": \"google_drive\",\n \"is_active\": true\n }'\n```", "operationId": "list_storage_connections_v1_organizations_connections_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStorageConnectionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections/{connection_identifier}": { "get": { "tags": [ "Organization Connections" ], "summary": "Get Storage Connection", "description": "Retrieve a storage connection by ID or name.\n\nReturns connection metadata including name, provider type, status, and\nhealth information. Credentials are automatically redacted from responses.\n\n**Identifier Resolution:**\n- If identifier starts with 'conn_', treated as connection ID\n- Otherwise, treated as connection name\n\n**Example:**\n```bash\n# By ID\ncurl -X GET \"http://localhost:8000/v1/organizations/connections/conn_abc123\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n\n# By name\ncurl -X GET \"http://localhost:8000/v1/organizations/connections/Marketing%20Drive\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```", "operationId": "get_storage_connection_v1_organizations_connections__connection_identifier__get", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Organization Connections" ], "summary": "Update Storage Connection", "description": "Update connection metadata or credentials.\n\nAllows partial updates to connection metadata without changing credentials.\nCredentials can be updated via provider_config. All changes are logged\nin audit trail.\n\n**What You Can Update:**\n- Connection name and description\n- Metadata tags\n- Status (active/suspended)\n- Provider credentials (via provider_config)\n\n**Example:**\n```bash\ncurl -X PATCH \"http://localhost:8000/v1/organizations/connections/conn_abc123\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Updated Drive Name\",\n \"status\": \"suspended\"\n }'\n```", "operationId": "update_storage_connection_v1_organizations_connections__connection_identifier__patch", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Organization Connections" ], "summary": "Delete Storage Connection", "description": "Soft-delete a connection (mark archived).\n\nPermanently retires a connection by marking it as ARCHIVED. The connection\ncannot be reactivated after deletion. Credentials are preserved for audit\npurposes but the connection is no longer usable.\n\n**Example:**\n```bash\ncurl -X DELETE \"http://localhost:8000/v1/organizations/connections/conn_abc123\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```", "operationId": "delete_storage_connection_v1_organizations_connections__connection_identifier__delete", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Delete Storage Connection V1 Organizations Connections Connection Identifier Delete" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections/{connection_identifier}/test": { "post": { "tags": [ "Organization Connections" ], "summary": "Test Storage Connection", "description": "Perform a credential test against the external provider.\n\nValidates that connection credentials are still valid and the provider\nis accessible. Result is logged in audit trail.\n\n**Use Cases:**\n- Validate credentials before using in sync operations\n- Diagnose connection issues\n- Refresh credentials after expiration\n\n**Example:**\n```bash\ncurl -X POST \"http://localhost:8000/v1/organizations/connections/conn_abc123/test\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```", "operationId": "test_storage_connection_v1_organizations_connections__connection_identifier__test_post", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConnectionTestResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections/{connection_identifier}/folders": { "get": { "tags": [ "Organization Connections" ], "summary": "List Google Drive Folders", "description": "List folders in Google Drive for folder selection in sync configuration.\n\nEnables users to browse and select folders when configuring sync operations.\nOnly available for Google Drive connections.\n\n**Use Cases:**\n- Browse available folders for sync configuration\n- Select source folder for bucket sync\n- Navigate nested folder structures\n\n**Example:**\n```bash\ncurl -X GET \"http://localhost:8000/v1/organizations/connections/conn_abc123/folders?path=/Marketing\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```", "operationId": "list_google_drive_folders_v1_organizations_connections__connection_identifier__folders_get", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "description": "Parent folder path to list from", "default": "/", "title": "Path" }, "description": "Parent folder path to list from" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFoldersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/connections/{connection_identifier}/files": { "get": { "tags": [ "Organization Connections" ], "summary": "List Google Drive Files", "description": "List files in Google Drive folder for preview.\n\nShows a preview of files in the selected folder when configuring sync operations.\nOnly available for Google Drive connections.\n\n**Use Cases:**\n- Preview files in a folder before selecting it for sync\n- Verify folder contains expected files\n- Check file types and counts\n\n**Example:**\n```bash\ncurl -X GET \"http://localhost:8000/v1/organizations/connections/conn_abc123/files?path=/Marketing&max_results=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```", "operationId": "list_google_drive_files_v1_organizations_connections__connection_identifier__files_get", "parameters": [ { "name": "connection_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs.", "examples": [ "conn_abc123def456ghi", "Marketing Google Drive" ], "title": "Connection Identifier" }, "description": "Connection identifier - either connection ID (conn_...) or name. The system will automatically resolve names to IDs." }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "description": "Folder path to list files from", "default": "/", "title": "Path" }, "description": "Folder path to list files from" }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of files to return", "default": 50, "title": "Max Results" }, "description": "Maximum number of files to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Google Drive Files V1 Organizations Connections Connection Identifier Files Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/users": { "post": { "tags": [ "Organization Users" ], "summary": "Create User", "description": "Create a new organization user.", "operationId": "create_user_v1_organizations_users_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create User V1 Organizations Users Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Organization Users" ], "summary": "List Users", "description": "List organization users with pagination and optional filters.", "operationId": "list_users_v1_organizations_users_get", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Skip" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "role", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/UserRole" }, { "type": "null" } ], "title": "Role" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Users V1 Organizations Users Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/users/{user_email}": { "get": { "tags": [ "Organization Users" ], "summary": "Get User", "description": "Return a user by email address.", "operationId": "get_user_v1_organizations_users__user_email__get", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get User V1 Organizations Users User Email Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Organization Users" ], "summary": "Update User", "description": "Apply partial updates to an existing user.", "operationId": "update_user_v1_organizations_users__user_email__patch", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update User V1 Organizations Users User Email Patch" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Organization Users" ], "summary": "Delete User", "description": "Delete a user and revoke their API keys.", "operationId": "delete_user_v1_organizations_users__user_email__delete", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/users/{user_email}/api-keys": { "post": { "tags": [ "Organization API Keys" ], "summary": "Create Api Key", "description": "Create a new API key for a user.", "operationId": "create_api_key_v1_organizations_users__user_email__api_keys_post", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Organization API Keys" ], "summary": "List Api Keys", "description": "List API keys for a user.", "operationId": "list_api_keys_v1_organizations_users__user_email__api_keys_get", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } }, { "name": "include_revoked", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Revoked" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response List Api Keys V1 Organizations Users User Email Api Keys Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/users/{user_email}/api-keys/{key_name}": { "patch": { "tags": [ "Organization API Keys" ], "summary": "Update Api Key", "description": "Update an API key's metadata or permissions.\n\n\ud83d\udd12 The \"admin-key\" is protected and cannot be modified.", "operationId": "update_api_key_v1_organizations_users__user_email__api_keys__key_name__patch", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } }, { "name": "key_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Organization API Keys" ], "summary": "Delete Api Key", "description": "Revoke an API key.\n\n\ud83d\udd12 The \"admin-key\" is protected and cannot be deleted.\n\nRefuses when a live published app still embeds this key, naming the app\n(MF-413). A 2026-06-03 revocation killed 2 published apps for seven weeks\nbecause nothing in this path looked for references and the call reported\nsuccess.", "operationId": "delete_api_key_v1_organizations_users__user_email__api_keys__key_name__delete", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } }, { "name": "key_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Name" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Revoke even when a live published app still embeds this key. Without it, the call is refused and names the apps that would break. Use force for a COMPROMISED key, where breaking them is the point.", "default": false, "title": "Force" }, "description": "Revoke even when a live published app still embeds this key. Without it, the call is refused and names the apps that would break. Use force for a COMPROMISED key, where breaking them is the point." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/users/{user_email}/api-keys/{key_name}/rotate": { "post": { "tags": [ "Organization API Keys" ], "summary": "Rotate Api Key", "description": "Rotate an API key and return the new secret.\n\n\ud83d\udd12 The \"admin-key\" is protected and cannot be rotated.", "operationId": "rotate_api_key_v1_organizations_users__user_email__api_keys__key_name__rotate_post", "parameters": [ { "name": "user_email", "in": "path", "required": true, "schema": { "type": "string", "title": "User Email" } }, { "name": "key_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/usage": { "get": { "tags": [ "Organization Usage" ], "summary": "Get Org Usage", "description": "Return aggregated usage for the organization.", "operationId": "get_org_usage_v1_organizations_usage_get", "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 start timestamp", "title": "Start" }, "description": "ISO8601 start timestamp" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 end timestamp", "title": "End" }, "description": "ISO8601 end timestamp" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Org Usage V1 Organizations Usage Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/api-keys/{key_id}/usage": { "get": { "tags": [ "Organization Usage" ], "summary": "Get Api Key Usage", "description": "Return usage metrics for a specific API key.", "operationId": "get_api_key_usage_v1_organizations_api_keys__key_id__usage_get", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 start timestamp", "title": "Start" }, "description": "ISO8601 start timestamp" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 end timestamp", "title": "End" }, "description": "ISO8601 end timestamp" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Api Key Usage V1 Organizations Api Keys Key Id Usage Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/api-keys/{key_id}/usage/endpoints": { "get": { "tags": [ "Organization Usage" ], "summary": "Get Api Key Endpoint Breakdown", "description": "Return endpoint-level usage metrics for a specific API key.", "operationId": "get_api_key_endpoint_breakdown_v1_organizations_api_keys__key_id__usage_endpoints_get", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 start timestamp", "title": "Start" }, "description": "ISO8601 start timestamp" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 end timestamp", "title": "End" }, "description": "ISO8601 end timestamp" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Api Key Endpoint Breakdown V1 Organizations Api Keys Key Id Usage Endpoints Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/audit/logs": { "get": { "tags": [ "Organization Audit" ], "summary": "List Audit Logs", "description": "List organization audit logs with filtering and pagination.\n\nReturns audit events for the organization, sorted by timestamp descending.\nRequires ADMIN permission.", "operationId": "list_audit_logs_v1_organizations_audit_logs_get", "parameters": [ { "name": "resource_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ResourceType-Input" }, { "type": "null" } ], "description": "Filter by resource type", "title": "Resource Type" }, "description": "Filter by resource type" }, { "name": "resource_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by resource ID", "title": "Resource Id" }, "description": "Filter by resource ID" }, { "name": "actor_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by actor ID", "title": "Actor Id" }, "description": "Filter by actor ID" }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/AuditAction" }, { "type": "null" } ], "description": "Filter by action", "title": "Action" }, "description": "Filter by action" }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 start timestamp", "title": "Start" }, "description": "ISO8601 start timestamp" }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO8601 end timestamp", "title": "End" }, "description": "ISO8601 end timestamp" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of results to skip", "default": 0, "title": "Skip" }, "description": "Number of results to skip" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Number of results to return", "default": 50, "title": "Limit" }, "description": "Number of results to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/audit/logs/{audit_id}": { "get": { "tags": [ "Organization Audit" ], "summary": "Get Audit Log", "description": "Get a specific audit log entry by ID.\n\nRequires ADMIN permission.", "operationId": "get_audit_log_v1_organizations_audit_logs__audit_id__get", "parameters": [ { "name": "audit_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Audit Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AuditEventResponse" }, { "type": "null" } ], "title": "Response Get Audit Log V1 Organizations Audit Logs Audit Id Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/audit/settings": { "get": { "tags": [ "Organization Audit" ], "summary": "Get Audit Settings", "description": "Get current audit configuration for the organization.\n\nReturns the audit settings including whether read auditing is enabled.\nRequires ADMIN permission.", "operationId": "get_audit_settings_v1_organizations_audit_settings_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditSettings" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Organization Audit" ], "summary": "Update Audit Settings", "description": "Update audit configuration for the organization.\n\nUse this to enable or disable read auditing.\nRequires ADMIN permission.", "operationId": "update_audit_settings_v1_organizations_audit_settings_patch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditSettings" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/secrets": { "post": { "tags": [ "Organization Secrets" ], "summary": "Create Secret", "description": "Create a new secret in organization vault.\n\n**Security**:\n- Secret value is encrypted at rest using Fernet encryption\n- Encrypted using ENCRYPTION_KEY from environment\n- Decrypted value is NEVER returned in API responses\n- Only secret names are exposed in list operations\n\n**Use Cases**:\n- Store API keys for external services (Stripe, GitHub, etc.)\n- Store authentication tokens for api_call retriever stage\n- Store credentials for third-party integrations\n\n**Important**:\n- Secret names must be unique within organization\n- Use update endpoint to modify existing secrets\n- Delete and recreate if you forget the value", "operationId": "create_secret_v1_organizations_secrets_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Organization Secrets" ], "summary": "List Secrets", "description": "List all secret names in organization vault.\n\n**Security**:\n- Returns ONLY secret names, never values\n- Use for discovering which secrets are configured\n- Secret values can only be retrieved by internal services\n\n**Response**:\n- List of secret names (e.g., ['stripe_api_key', 'github_token'])\n- Total count of secrets", "operationId": "list_secrets_v1_organizations_secrets_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/secrets/{secret_name}": { "put": { "tags": [ "Organization Secrets" ], "summary": "Update Secret", "description": "Update an existing secret in organization vault.\n\n**Security**:\n- Replaces existing encrypted value with new encrypted value\n- Old value is permanently overwritten\n- No history or audit trail of previous values\n\n**Use Cases**:\n- Rotate API keys periodically\n- Update expired tokens\n- Change credentials after security incident", "operationId": "update_secret_v1_organizations_secrets__secret_name__put", "parameters": [ { "name": "secret_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Secret Name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecretRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Organization Secrets" ], "summary": "Delete Secret", "description": "Delete a secret from organization vault.\n\n**Warning**:\n- Deletion is permanent and immediate\n- Any api_call stages using this secret will fail\n- No confirmation prompt - use with caution\n\n**Use Cases**:\n- Remove unused credentials\n- Clean up after service decommissioning\n- Security incident response", "operationId": "delete_secret_v1_organizations_secrets__secret_name__delete", "parameters": [ { "name": "secret_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Secret Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/dsar/export": { "post": { "tags": [ "Data Subject Access Requests" ], "summary": "Request Data Export", "description": "Request a full data export for this organization.\n\nReturns a summary of all data categories that will be exported.\nThe export is processed asynchronously and delivered within 30 days\nas required by GDPR Article 15 and CCPA Section 1798.100.\n\nRequires ADMIN permission.", "operationId": "request_data_export_v1_organizations_dsar_export_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DSARExportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/dsar/delete": { "post": { "tags": [ "Data Subject Access Requests" ], "summary": "Request Data Deletion", "description": "Request deletion of all organization data.\n\nThis is a DSAR deletion request per GDPR Article 17 (Right to Erasure)\nand CCPA Section 1798.105. The request is logged and processed within\n30 days. Once executed, this action is IRREVERSIBLE.\n\nThe actual deletion is performed by the delete_organization_resources_flow\nafter verification. This endpoint creates the request record.\n\nRequires ADMIN permission.", "operationId": "request_data_deletion_v1_organizations_dsar_delete_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DSARDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/dsar/status": { "get": { "tags": [ "Data Subject Access Requests" ], "summary": "List Dsar Requests", "description": "List all DSAR requests for this organization.\n\nReturns the status of all pending and completed data subject\naccess requests (exports and deletions).\n\nRequires ADMIN permission.", "operationId": "list_dsar_requests_v1_organizations_dsar_status_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DSARStatusResponse" }, "title": "Response List Dsar Requests V1 Organizations Dsar Status Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/estimate": { "post": { "tags": [ "Organization Billing" ], "summary": "Estimate Cost", "description": "Quote the v2 cost of planned ingestion before submitting it.\n\nForgiving by design: unknown MIME types quote at the cheapest band;\nwrong unit fields and inapplicable features return teaching errors.", "operationId": "estimate_cost_v1_organizations_billing_estimate_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/generate-invoice": { "post": { "tags": [ "Organization Billing" ], "summary": "Generate Invoice Now", "description": "Manually trigger invoice generation for this organization.\n\nUseful for testing the billing flow or generating retroactive invoices.\nRequires ADMIN permission.\n\nLine items follow the v2 (modality+features, D8) composition: flat monthly\nfee + per-modality feature usage in natural units and dollars + the plan's\nincluded-usage pool as a deduction; only usage beyond the pool is due. The\ntotal always reconciles to the month's ledger charges (see `pricing_v2`).\n\n**Example:**\n```python\n# Dry run\nresponse = await client.post(\n \"/v1/organizations/billing/generate-invoice\",\n json={\"dry_run\": true}\n)\n\n# Actually generate\nresponse = await client.post(\n \"/v1/organizations/billing/generate-invoice\",\n json={\"billing_month\": \"2026-01\"}\n)\n```", "operationId": "generate_invoice_now_v1_organizations_billing_generate_invoice_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_generate_invoice_now_v1_organizations_billing_generate_invoice_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Generate Invoice Now V1 Organizations Billing Generate Invoice Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/balance": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Credit Balance", "description": "Get current credit balance and tier information.\n\nReturns the organization's credit balance, current tier, and usage statistics.\nUseful for displaying billing status in dashboards.\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\nresponse = await client.get(\"/v1/organizations/billing/balance\")\nprint(f\"Balance: {response['credit_balance']} credits\")\nprint(f\"Tier: {response['account_tier']}\")\n```", "operationId": "get_credit_balance_v1_organizations_billing_balance_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/setup-payment-method": { "post": { "tags": [ "Organization Billing" ], "summary": "Setup Payment Method", "description": "Initialize payment method setup flow.\n\nCreates a Stripe SetupIntent for collecting payment method without charging.\nThe client_secret should be used with Stripe Elements on the frontend.\n\n**Flow:**\n1. Frontend calls this endpoint\n2. Backend creates Stripe Customer (if needed) and SetupIntent\n3. Frontend uses client_secret with Stripe Elements\n4. User enters card details\n5. Frontend calls confirm-payment-method endpoint\n\n**Requirements:**\n- Admin permission (only org admins can set up payment methods)\n\n**Example:**\n```python\nresponse = await client.post(\"/v1/organizations/billing/setup-payment-method\")\nclient_secret = response[\"client_secret\"]\n# Use client_secret with Stripe Elements\n```", "operationId": "setup_payment_method_v1_organizations_billing_setup_payment_method_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupPaymentMethodResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/confirm-payment-method": { "post": { "tags": [ "Organization Billing" ], "summary": "Confirm Payment Method", "description": "Confirm payment method after frontend collects it.\n\nAfter Stripe Elements confirms the SetupIntent, call this endpoint\nto attach the payment method to the customer and enable auto-billing.\n\n**Requirements:**\n- Admin permission\n- Must have called setup-payment-method first\n\n**Example:**\n```python\n# After Stripe Elements confirms setup\nresponse = await client.post(\n \"/v1/organizations/billing/confirm-payment-method\",\n json={\"payment_method_id\": \"pm_1ABC2DEF3GHI\"}\n)\n```", "operationId": "confirm_payment_method_v1_organizations_billing_confirm_payment_method_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentMethodRequest", "description": "Payment method confirmation" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentMethodResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/payment-method": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Payment Method", "description": "Get current payment method.\n\nReturns the saved payment method details (last 4 digits, brand)\nand auto-billing status.\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\nresponse = await client.get(\"/v1/organizations/billing/payment-method\")\nif response[\"has_payment_method\"]:\n print(f\"Card: {response['payment_method']['card_brand']} ****{response['payment_method']['card_last4']}\")\n```", "operationId": "get_payment_method_v1_organizations_billing_payment_method_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentMethodResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/enable-auto-billing": { "post": { "tags": [ "Organization Billing" ], "summary": "Enable Auto Billing", "description": "Enable automatic monthly billing.\n\nRe-enables automatic billing if it was previously disabled.\nPayment method must already be saved.\n\n**Requirements:**\n- Admin permission\n- Must have payment method saved\n\n**Example:**\n```python\nresponse = await client.post(\"/v1/organizations/billing/enable-auto-billing\")\n```", "operationId": "enable_auto_billing_v1_organizations_billing_enable_auto_billing_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBillingToggleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/disable-auto-billing": { "post": { "tags": [ "Organization Billing" ], "summary": "Disable Auto Billing", "description": "Disable automatic monthly billing.\n\nDisables automatic billing but keeps payment method saved.\nOrganization can re-enable later or pay invoices manually.\n\n**Requirements:**\n- Admin permission\n\n**Example:**\n```python\nresponse = await client.post(\"/v1/organizations/billing/disable-auto-billing\")\n```", "operationId": "disable_auto_billing_v1_organizations_billing_disable_auto_billing_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoBillingToggleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/usage/current": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Current Usage", "description": "Get current month usage.\n\nReturns credit consumption for the current billing period,\nestimated cost, and next invoice date.\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\nresponse = await client.get(\"/v1/organizations/billing/usage/current\")\nprint(f\"Usage: {response['current_month_usage']} credits\")\nprint(f\"Estimated cost: ${response['estimated_cost_usd']}\")\n```", "operationId": "get_current_usage_v1_organizations_billing_usage_current_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUsageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/usage/breakdown": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Usage Breakdown", "description": "Get detailed usage breakdown.\n\nReturns usage breakdown by operation type and extractor\nfor the specified billing period.\n\n**Query Parameters:**\n- `billing_month`: Month to query (YYYY-MM format, defaults to current)\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\n# Current month\nresponse = await client.get(\"/v1/organizations/billing/usage/breakdown\")\n\n# Specific month\nresponse = await client.get(\n \"/v1/organizations/billing/usage/breakdown\",\n params={\"billing_month\": \"2025-11\"}\n)\n```", "operationId": "get_usage_breakdown_v1_organizations_billing_usage_breakdown_get", "parameters": [ { "name": "billing_month", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Billing month in YYYY-MM format (defaults to current month)", "examples": [ "2025-12" ], "title": "Billing Month" }, "description": "Billing month in YYYY-MM format (defaults to current month)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBreakdownResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/transactions": { "get": { "tags": [ "Organization Billing" ], "summary": "List Transactions", "description": "List individual credit-usage transactions (most recent first).\n\nThe per-operation **credit ledger**: every credit debit, what consumed it\n(operation/extractor/resource), and when \u2014 the transaction-level itemization\nbeyond the aggregated `/usage/breakdown` totals.\n\n**Query Parameters:**\n- `limit`: page size (1-200, default 50)\n- `offset`: records to skip\n- `billing_month`: optional YYYY-MM filter\n\n**Requirements:** Read permission.\n\n**Example:**\n```python\nresponse = await client.get(\n \"/v1/organizations/billing/transactions\",\n params={\"limit\": 50, \"billing_month\": \"2026-06\"},\n)\n```", "operationId": "list_transactions_v1_organizations_billing_transactions_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (max 200)", "examples": [ 50 ], "default": 50, "title": "Limit" }, "description": "Page size (max 200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Records to skip (pagination)", "default": 0, "title": "Offset" }, "description": "Records to skip (pagination)" }, { "name": "billing_month", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional YYYY-MM filter (defaults to all months)", "examples": [ "2026-06" ], "title": "Billing Month" }, "description": "Optional YYYY-MM filter (defaults to all months)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/usage/vector-backend": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Vector Backend Usage", "description": "Get vector backend usage breakdown.\n\nReturns usage dimensions (vectors stored, storage, queries, writes) and\ncost breakdown for the tenant's active vector backend. Works for all\nbackends: qdrant, mvs, and dual_write.\n\n**Requirements:**\n- Read permission", "operationId": "get_vector_backend_usage_v1_organizations_billing_usage_vector_backend_get", "parameters": [ { "name": "billing_month", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Billing month in YYYY-MM format (defaults to current month)", "examples": [ "2026-05" ], "title": "Billing Month" }, "description": "Billing month in YYYY-MM format (defaults to current month)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VectorBackendUsageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/invoices": { "get": { "tags": [ "Organization Billing" ], "summary": "List Invoices", "description": "List monthly invoices.\n\nReturns paginated list of monthly invoices with links to\nStripe-hosted invoice pages.\n\n**Query Parameters:**\n- `limit`: Number of invoices (1-100, default 10)\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\nresponse = await client.get(\"/v1/organizations/billing/invoices?limit=10\")\nfor invoice in response[\"invoices\"]:\n print(f\"{invoice['billing_month']}: ${invoice['amount_paid']/100}\")\n```", "operationId": "list_invoices_v1_organizations_billing_invoices_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of invoices to return", "default": 10, "title": "Limit" }, "description": "Number of invoices to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/spending-caps": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Spending Caps", "description": "Get current spending cap configuration.\n\nReturns spending cap settings including budget limits, alert thresholds,\nand current spending status.\n\n**Requirements:**\n- Read permission\n\n**Example:**\n```python\nresponse = await client.get(\"/v1/organizations/billing/spending-caps\")\nprint(f\"Monthly budget: ${response['monthly_spending_budget_usd']}\")\nprint(f\"Hard cap enabled: {response['hard_cap_enabled']}\")\nprint(f\"Current spending: ${response['current_spending_usd']}\")\n```", "operationId": "get_spending_caps_v1_organizations_billing_spending_caps_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingCapsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Organization Billing" ], "summary": "Update Spending Caps", "description": "Update spending cap configuration.\n\nConfigure spending limits and alert thresholds to control costs.\n\n**Features:**\n- **Soft Limit (Budget)**: Triggers alerts but doesn't block API access\n- **Hard Cap**: Blocks API access when reached. Setting a positive\n `hard_spending_cap` arms enforcement automatically; pass\n `hard_cap_enabled: false` in the same request to set the cap without\n enforcing it. Clearing the cap (null/0) disarms enforcement.\n- **Alert Thresholds**: Customize when to receive spending notifications\n\n**Requirements:**\n- Admin permission\n- Only applies to organizations with auto-billing enabled\n\n**Example:**\n```python\n# Set $100 budget with alerts at 75% and 100%\nresponse = await client.post(\n \"/v1/organizations/billing/spending-caps\",\n json={\n \"monthly_spending_budget\": 10000, # $100 in cents\n \"spending_alert_thresholds\": [75, 100],\n \"spending_alerts_enabled\": True,\n }\n)\n\n# Enable hard cap at $500\nresponse = await client.post(\n \"/v1/organizations/billing/spending-caps\",\n json={\n \"hard_spending_cap\": 50000, # $500 in cents\n \"hard_cap_enabled\": True,\n }\n)\n\n# Disable all spending limits\nresponse = await client.post(\n \"/v1/organizations/billing/spending-caps\",\n json={\n \"monthly_spending_budget\": None,\n \"hard_spending_cap\": None,\n \"hard_cap_enabled\": False,\n }\n)\n```", "operationId": "update_spending_caps_v1_organizations_billing_spending_caps_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSpendingCapsRequest", "description": "Spending cap configuration" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingCapsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/checkout": { "post": { "tags": [ "Organization Billing" ], "summary": "Create Checkout", "description": "Create a Stripe Checkout Session for a one-time credit purchase.\n\nAllows organization admins to purchase credit packages via Stripe Checkout.\nAfter successful payment, credits are automatically added to the organization.\n\n**Available Packages:**\n- `starter`: 10,000 credits \u2014 $10\n- `growth`: 50,000 credits \u2014 $40\n- `scale`: 200,000 credits \u2014 $120\n\n**Requirements:**\n- Admin permission\n\n**Example:**\n```python\nresponse = await client.post(\n \"/v1/organizations/billing/checkout\",\n json={\"package\": \"growth\"}\n)\n# Redirect user to response[\"checkout_url\"]\n```", "operationId": "create_checkout_v1_organizations_billing_checkout_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest", "description": "Credit package checkout request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/subscribe": { "post": { "tags": [ "Organization Billing" ], "summary": "Subscribe To Plan", "description": "Subscribe to a paid plan via Stripe Checkout.\n\nCreates a Stripe Checkout Session in subscription mode. After payment,\nthe organization's account_type is updated via webhook.\n\nIf the organization already has an active subscription, the plan is\nchanged inline (upgrade/downgrade with proration) instead of creating\na new checkout session.\n\n**Available Plans** (tier minimum is a billing floor; usage above it\nbills automatically):\n- `managed_build`: Managed Mixpeek Build \u2014 $25/mo min, 100K objects/mo\n- `managed_scale`: Managed Mixpeek Scale \u2014 $250/mo min, 1M objects/mo\n- `mvs_build`: MVS Standalone Build \u2014 $25/mo min, 1M vectors\n- `mvs_scale`: MVS Standalone Scale \u2014 $250/mo min, 25M vectors\n\n**Discounts:** each non-empty `onboarding_answers` field takes $5 off the\nfirst invoice (max $10). An explicit `promo_code` is validated and\npre-applied; when both are sent the promo takes checkout's single\ndiscount slot and the onboarding credit lands on the customer balance.\nWithout either, Stripe's own promo-code field is enabled at checkout.", "operationId": "subscribe_to_plan_v1_organizations_billing_subscribe_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/portal": { "post": { "tags": [ "Organization Billing" ], "summary": "Open Billing Portal", "description": "Open the Stripe customer billing portal.\n\nThis is the correct destination for a \"Manage subscription\" action: the\nportal lets an existing customer update their card, view/download invoices,\nand change or cancel their plan. It is NOT the same as POST /subscribe \u2014\nre-running /subscribe for an existing subscriber starts a brand-new checkout\ninstead of managing the current one.\n\nRequires an existing Stripe customer. Orgs that have never started billing\nhave nothing to manage, so they get an actionable 400 pointing at /subscribe.", "operationId": "open_billing_portal_v1_organizations_billing_portal_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalRequest", "default": { "return_url": "https://studio.mixpeek.com/billing" } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPortalResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/subscription": { "get": { "tags": [ "Organization Billing" ], "summary": "Get Subscription Status", "description": "Get current subscription status.", "operationId": "get_subscription_status_v1_organizations_billing_subscription_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/subscription/cancel": { "post": { "tags": [ "Organization Billing" ], "summary": "Cancel Subscription", "description": "Cancel the current subscription.\n\nDefault: cancel at end of billing period (the subscription remains\nactive until then, after which the organization downgrades). With\n``immediate=true`` (BACKE-2859): cancel NOW \u2014 the org-deletion cascade\nand teardown callers need a cancel that actually ends billing today\ninstead of leaving a live sub on the card.", "operationId": "cancel_subscription_v1_organizations_billing_subscription_cancel_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CancelSubscriptionRequest" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/apply-promo": { "post": { "tags": [ "Organization Billing" ], "summary": "Apply Promo", "description": "Apply a promo code to the organization's active subscription.\n\nEvery failure carries a reason (invalid / expired / exhausted / product\nmismatch / no subscription) \u2014 never a silent no-op.", "operationId": "apply_promo_v1_organizations_billing_apply_promo_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPromoRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPromoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/billing/redeem-promo": { "post": { "tags": [ "Organization Billing" ], "summary": "Redeem Promo", "description": "Redeem a promo code on a FRESH org \u2014 no Checkout, no card (BACKE-2854).\n\nEthan directive 2026-07-22: a promo code must let the user continue\nwithout entering a CC. This creates the subscription server-side with the\ncoupon attached (the self-serve twin of the manual comp flow), stamps\n``metadata.organization_id`` so the subscription webhook grants tier +\nPOC cap, and sets the org's plan fields inline so the user continues\nIMMEDIATELY (no webhook-latency paywall).\n\nOnly codes whose window bills $0 (percent_off=100 \u2014 every POC code by\nvalidated shape) can start service card-less: a partial discount with no\npayment method would generate a FAILING first invoice (service cut +\ndunning \u2014 strictly worse than the card form; the uncollectable shape\nPOC-PROMO-CAP-2026-07-17 exists to prevent). Partial codes get a clear\nredirect to checkout, where the discount still applies. Card-ask happens\nat coupon end (finances' T-7d lifecycle).\n\nEvery failure carries a reason \u2014 never a silent no-op.", "operationId": "redeem_promo_v1_organizations_billing_redeem_promo_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemPromoRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemPromoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/infrastructure/summary": { "get": { "tags": [ "Organization Infrastructure" ], "summary": "Get Infrastructure", "description": "Get infrastructure summary for an enterprise single-tenant deployment.\n\nReturns compute profiles for each extractor, cloud cost breakdown\nwith transparent margin, and the billing period summary for the\nrequested (default: current) month. Enterprise-only endpoint.", "operationId": "get_infrastructure_v1_organizations_infrastructure_summary_get", "parameters": [ { "name": "billing_month", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Billing month to inspect (YYYY-MM). Defaults to the current month. Past months return the same category + line-item granularity as the current month.", "examples": [ "2026-06" ], "title": "Billing Month" }, "description": "Billing month to inspect (YYYY-MM). Defaults to the current month. Past months return the same category + line-item granularity as the current month." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfrastructureSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/targets": { "get": { "tags": [ "Organization Targets" ], "summary": "Get Organization Targets", "description": "Get this organization's resource + SLO targets.\n\nTenancy (dedicated vs shared) is resolved SERVER-SIDE from the org \u2014\nnever from a client-supplied header (BACKE-2564). ``targets_writable``\nis the capability flag a client should read rather than infer from\n``plane``: shared-plane orgs are always read-only by platform policy;\ndedicated orgs may write once the write path ships (not this\nendpoint).", "operationId": "get_organization_targets_v1_organizations_targets_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetSpec" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/billing/pricing": { "get": { "tags": [ "Pricing" ], "summary": "Get Pricing Configuration", "description": "Public pricing rate card. Price = how much content of each file type \u00d7 (base rate + the search-by features enabled). Returns per-modality rates, tier usage pools, and plan definitions. No authentication required.", "operationId": "get_pricing_config_v1_billing_pricing_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/buckets/{bucket_id}/source-adapter/status": { "get": { "tags": [ "Source Adapter" ], "summary": "Get Adapter Status", "description": "Get source adapter status and statistics.", "operationId": "get_adapter_status_v1_buckets__bucket_id__source_adapter_status_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Adapter Status V1 Buckets Bucket Id Source Adapter Status Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/public/notifications/unsubscribe": { "get": { "tags": [ "Public Notifications API" ], "summary": "Unsubscribe From Nudges", "description": "Unsubscribe from nudge emails using a signed token.\n\nThis is a public endpoint (no auth required) for one-click unsubscribe\nfrom email links. The token is cryptographically signed and contains\nthe organization ID and nudge type.", "operationId": "unsubscribe_from_nudges_v1_public_notifications_unsubscribe_get", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "description": "Signed unsubscribe token from email", "title": "Token" }, "description": "Signed unsubscribe token from email" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/templates/namespaces": { "get": { "tags": [ "Templates", "Namespace Templates" ], "summary": "List Namespace Templates", "description": "List namespace templates (system + organization + user).", "operationId": "list_namespace_templates_v1_templates_namespaces_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "scope", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/TemplateScope" }, { "type": "null" } ], "description": "Filter by scope (system, organization, or user)", "title": "Scope" }, "description": "Filter by scope (system, organization, or user)" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Show only active templates", "default": true, "title": "Is Active" }, "description": "Show only active templates" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseTemplateModel" }, "title": "Response List Namespace Templates V1 Templates Namespaces Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/namespaces/{template_id}": { "get": { "tags": [ "Templates", "Namespace Templates" ], "summary": "Get Namespace Template", "description": "Get namespace template details.", "operationId": "get_namespace_template_v1_templates_namespaces__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/namespaces/from-namespace/{namespace_id}": { "post": { "tags": [ "Templates", "Namespace Templates" ], "summary": "Create Namespace Template", "description": "Create template from existing namespace.\n\nSupports three template scopes:\n- **organization**: Available to all users in your organization (default)\n- **user**: Available only to you\n- **system**: Available to all organizations (requires Mixpeek admin email)", "operationId": "create_namespace_template_v1_templates_namespaces_from_namespace__namespace_id__post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace ID", "title": "Namespace Id" }, "description": "Namespace ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/namespaces/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Namespace Templates" ], "summary": "Instantiate Namespace Template", "description": "Instantiate namespace template.", "operationId": "instantiate_namespace_template_v1_templates_namespaces__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/retrievers": { "post": { "tags": [ "Templates", "Retriever Templates" ], "summary": "List Retriever Templates", "description": "List retriever templates (system + organization + user).\n\nSupports filtering, sorting, and search like other list operations.\n\n**Request Body (optional):**\n- `filters`: Attribute-based filters `{\"AND\": [{\"field\": \"category\", \"operator\": \"eq\", \"value\": \"semantic_search\"}]}`\n- `sort`: Sort options `{\"field\": \"name\", \"direction\": \"asc\"}`\n- `search`: Wildcard search across template_id, name, description, tags\n- `scope`: Filter by scope (system, organization, user)\n- `category`: Filter by category\n- `is_active`: Show only active templates (default: true)\n- `tags`: Filter by tags (templates must have ALL specified tags)", "operationId": "list_retriever_templates_v1_templates_retrievers_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/retrievers/{template_id}": { "get": { "tags": [ "Templates", "Retriever Templates" ], "summary": "Get Retriever Template", "description": "Get retriever template details.", "operationId": "get_retriever_template_v1_templates_retrievers__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/retrievers/from-retriever/{retriever_id}": { "post": { "tags": [ "Templates", "Retriever Templates" ], "summary": "Create Retriever Template", "description": "Create template from existing retriever.\n\nSupports three template scopes:\n- **organization**: Available to all users in your organization (default)\n- **user**: Available only to you\n- **system**: Available to all organizations (requires Mixpeek admin email)", "operationId": "create_retriever_template_v1_templates_retrievers_from_retriever__retriever_id__post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Retriever ID", "title": "Retriever Id" }, "description": "Retriever ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/retrievers/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Retriever Templates" ], "summary": "Instantiate Retriever Template", "description": "Instantiate retriever template.", "operationId": "instantiate_retriever_template_v1_templates_retrievers__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateRetrieverTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedRetrieverTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/clusters": { "post": { "tags": [ "Templates", "Cluster Templates" ], "summary": "List Cluster Templates", "description": "List cluster templates (system + organization + user).\n\nSupports filtering, sorting, and search like other list operations.", "operationId": "list_cluster_templates_v1_templates_clusters_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/clusters/{template_id}": { "get": { "tags": [ "Templates", "Cluster Templates" ], "summary": "Get Cluster Template", "description": "Get cluster template details.", "operationId": "get_cluster_template_v1_templates_clusters__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/clusters/from-cluster/{cluster_id}": { "post": { "tags": [ "Templates", "Cluster Templates" ], "summary": "Create Cluster Template", "description": "Create template from existing cluster.", "operationId": "create_cluster_template_v1_templates_clusters_from_cluster__cluster_id__post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/clusters/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Cluster Templates" ], "summary": "Instantiate Cluster Template", "description": "Instantiate cluster template.", "operationId": "instantiate_cluster_template_v1_templates_clusters__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateClusterTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedClusterTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/collections": { "post": { "tags": [ "Templates", "Collection Templates" ], "summary": "List Collection Templates", "description": "List collection templates (system + organization + user).\n\nSupports filtering, sorting, and search like other list operations.", "operationId": "list_collection_templates_v1_templates_collections_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/collections/{template_id}": { "get": { "tags": [ "Templates", "Collection Templates" ], "summary": "Get Collection Template", "description": "Get collection template details.", "operationId": "get_collection_template_v1_templates_collections__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/collections/from-collection/{collection_id}": { "post": { "tags": [ "Templates", "Collection Templates" ], "summary": "Create Collection Template", "description": "Create template from existing collection.\n\nSupports three template scopes:\n- **organization**: Available to all users in your organization (default)\n- **user**: Available only to you\n- **system**: Available to all organizations (requires Mixpeek admin email)", "operationId": "create_collection_template_v1_templates_collections_from_collection__collection_id__post", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID", "title": "Collection Id" }, "description": "Collection ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/collections/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Collection Templates" ], "summary": "Instantiate Collection Template", "description": "Instantiate collection template.", "operationId": "instantiate_collection_template_v1_templates_collections__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateCollectionTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedCollectionTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/buckets": { "post": { "tags": [ "Templates", "Bucket Templates" ], "summary": "List Bucket Templates", "description": "List bucket templates (system + organization + user).\n\nSupports filtering, sorting, and search like other list operations.", "operationId": "list_bucket_templates_v1_templates_buckets_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/buckets/{template_id}": { "get": { "tags": [ "Templates", "Bucket Templates" ], "summary": "Get Bucket Template", "description": "Get bucket template details.", "operationId": "get_bucket_template_v1_templates_buckets__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/buckets/from-bucket/{bucket_id}": { "post": { "tags": [ "Templates", "Bucket Templates" ], "summary": "Create Bucket Template", "description": "Create template from existing bucket.\n\nSupports three template scopes:\n- **organization**: Available to all users in your organization (default)\n- **user**: Available only to you\n- **system**: Available to all organizations (requires Mixpeek admin email)", "operationId": "create_bucket_template_v1_templates_buckets_from_bucket__bucket_id__post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Bucket ID", "title": "Bucket Id" }, "description": "Bucket ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/buckets/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Bucket Templates" ], "summary": "Instantiate Bucket Template", "description": "Instantiate bucket template.", "operationId": "instantiate_bucket_template_v1_templates_buckets__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateBucketTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedBucketTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/taxonomies": { "post": { "tags": [ "Templates", "Taxonomy Templates" ], "summary": "List Taxonomy Templates", "description": "List taxonomy templates (system + organization + user).\n\nSupports filtering, sorting, and search like other list operations.", "operationId": "list_taxonomy_templates_v1_templates_taxonomies_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/taxonomies/{template_id}": { "get": { "tags": [ "Templates", "Taxonomy Templates" ], "summary": "Get Taxonomy Template", "description": "Get taxonomy template details.", "operationId": "get_taxonomy_template_v1_templates_taxonomies__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseTemplateModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/taxonomies/from-taxonomy/{taxonomy_id}": { "post": { "tags": [ "Templates", "Taxonomy Templates" ], "summary": "Create Taxonomy Template", "description": "Create template from existing taxonomy.\n\nSupports three template scopes:\n- **organization**: Available to all users in your organization (default)\n- **user**: Available only to you\n- **system**: Available to all organizations (requires Mixpeek admin email)", "operationId": "create_taxonomy_template_v1_templates_taxonomies_from_taxonomy__taxonomy_id__post", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID", "title": "Taxonomy Id" }, "description": "Taxonomy ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateFromResourceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/taxonomies/{template_id}/instantiate": { "post": { "tags": [ "Templates", "Taxonomy Templates" ], "summary": "Instantiate Taxonomy Template", "description": "Instantiate taxonomy template.", "operationId": "instantiate_taxonomy_template_v1_templates_taxonomies__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Template ID", "title": "Template Id" }, "description": "Template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateTaxonomyTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedTaxonomyTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/templates/scaffolds/default": { "post": { "tags": [ "Scaffold Templates" ], "summary": "Get Or Create Default Namespace", "description": "Get or create the default universal namespace.\n\nReturns the existing default namespace if one exists, or creates a new one\nusing the universal template. This is the primary onboarding entry point \u2014\nStudio calls this on first upload to ensure a namespace exists without\nrequiring the user to choose a template.\n\nThe default namespace supports all file types (video, image, audio, PDF, text)\nwith pre-configured extractors and a universal retriever.\n\nIf the request carries an `X-Namespace` header that resolves to an existing\nwritable org namespace (e.g. one just created via the wizard), the scaffold\nis provisioned into THAT namespace instead of creating a \"default\" one.", "operationId": "get_or_create_default_namespace_v1_templates_scaffolds_default_post", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedScaffoldResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/templates/scaffolds/{template_id}/manifest": { "get": { "tags": [ "Scaffold Templates" ], "summary": "Get Scaffold Template Manifest", "description": "Render a scaffold template as a Mixpeek manifest.\n\nConverts the scaffold's configuration (namespace, bucket, collections,\nretriever, taxonomies, clusters) into declarative Infrastructure-as-Code\nYAML \u2014 the same format used by `POST /v1/manifest/apply` and\n`GET /v1/manifest/export`.\n\nReturns both the YAML string (`manifest_yaml`) and the parsed manifest\ndict (`manifest`).", "operationId": "get_scaffold_template_manifest_v1_templates_scaffolds__template_id__manifest_get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Scaffold template ID", "title": "Template Id" }, "description": "Scaffold template ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScaffoldManifestResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/templates/scaffolds/{template_id}/instantiate": { "post": { "tags": [ "Scaffold Templates" ], "summary": "Instantiate Scaffold Template", "description": "Create complete infrastructure from scaffold template.\n\nCreates all resources atomically:\n1. **Namespace** with configured feature extractors\n2. **Bucket** with schema for your data structure\n3. **Collection** linked to bucket with feature config\n4. **Retriever** with search pipeline stages\n\nAll resources are empty, ready for data upload.\n\n**Next Steps:**\n1. Upload data: `POST /v1/buckets/{bucket_id}/objects`\n2. Process batch: `POST /v1/collections/{collection_id}/batches`\n3. Search: `POST /v1/retrievers/{retriever_id}/retrieve`\n\n**Example Request:**\n```json\n{\n \"namespace_name\": \"my_video_app\",\n \"namespace_description\": \"Video search application\"\n}\n```", "operationId": "instantiate_scaffold_template_v1_templates_scaffolds__template_id__instantiate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Scaffold template ID", "title": "Template Id" }, "description": "Scaffold template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateScaffoldRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiatedScaffoldResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/quickstart/docs-search": { "post": { "tags": [ "Quickstart" ], "summary": "Provision Docs Search", "description": "One-call provisioning of a complete documentation search pipeline. Creates a namespace, bucket, web crawl collection, retriever with semantic + code search, publishes it, and generates a scoped API key. Returns everything needed to embed the search widget.", "operationId": "provision_docs_search_v1_quickstart_docs_search_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/onboarding/infer-config": { "post": { "tags": [ "Onboarding" ], "summary": "Infer onboarding configuration", "description": "Given a free-text use-case description, uses an LLM to recommend the best scaffold template, extractors, retriever stages, and sample queries for the user's project.", "operationId": "infer_config_v1_onboarding_infer_config_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferConfigRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/onboarding/suggested-config": { "get": { "tags": [ "Onboarding" ], "summary": "Get the org's signup-time suggested namespace", "description": "Returns the namespace configuration that was suggested from Mixpeek's company research at signup, if one was provisioned. Studio uses this to badge the suggested namespace.", "operationId": "get_suggested_config_v1_onboarding_suggested_config_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/apply": { "post": { "tags": [ "Manifest" ], "summary": "Apply Manifest", "description": "Apply a YAML manifest to create resources.\n\nCreates all resources defined in the manifest file in dependency order.\nFails if any resource already exists (create-only mode).\nPerforms automatic rollback if any resource creation fails.\n\n**Features:**\n- Topological sorting ensures resources are created in correct dependency order\n- Secret references (`${{ secrets.NAME }}`) are resolved from organization secrets\n- Atomic operation: rolls back all created resources if any creation fails\n- Dry run mode validates the manifest without making changes\n\n**Example:**\n```bash\ncurl -X POST /v1/manifest/apply \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -H \"X-Namespace: ns_xxx\" \\\n -F \"manifest_file=@mixpeek.yaml\"\n```\n\n**Example manifest:**\n```yaml\nversion: \"1.0\"\nmetadata:\n name: \"my-environment\"\n\nnamespaces:\n - name: video_search\n feature_extractors:\n - name: multimodal_extractor\n version: v1\n\nbuckets:\n - name: raw_videos\n namespace: video_search\n schema:\n properties:\n video: { type: video }\n```", "operationId": "apply_manifest_v1_manifest_apply_post", "parameters": [ { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Validate only, don't create resources", "default": false, "title": "Dry Run" }, "description": "Validate only, don't create resources" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_apply_manifest_v1_manifest_apply_post" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/validate": { "post": { "tags": [ "Manifest" ], "summary": "Validate Manifest", "description": "Validate a YAML manifest without applying.\n\nChecks:\n- YAML syntax validity\n- Schema validation against manifest models\n- Cross-resource reference validation\n- Dependency resolution (no circular dependencies)\n- Secret reference existence\n\nReturns detailed validation results including:\n- Resource counts by type\n- Missing secrets that need to be configured\n- Validation errors and warnings\n\n**Example:**\n```bash\ncurl -X POST /v1/manifest/validate \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -F \"manifest_file=@mixpeek.yaml\"\n```", "operationId": "validate_manifest_v1_manifest_validate_post", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_validate_manifest_v1_manifest_validate_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/lint": { "post": { "tags": [ "Manifest" ], "summary": "Lint Manifest", "description": "Lint a YAML manifest for best practices and potential issues.\n\nGoes beyond basic validation to provide actionable suggestions for\nimproving your manifest configuration. This endpoint is designed for\nAI agents and developers who want to optimize their Mixpeek setup.\n\n**Lint Rules:**\n- `UNUSED_EXTRACTOR`: Feature extractor defined but not used by any collection\n- `UNUSED_COLLECTION`: Collection not referenced by any retriever\n- `MISSING_INPUT_SCHEMA`: Retriever uses templates but has no input_schema\n- `MISSING_CACHE_CONFIG`: Retriever without caching (especially with LLM stages)\n- `SUBOPTIMAL_STAGE_ORDER`: Filter stages after expensive operations\n- `DUPLICATE_FEATURE_URI`: Same feature searched multiple times\n- `MISSING_DESCRIPTION`: Resources without descriptions\n- `NO_SEARCH_STAGE`: Retriever with no search stages\n- `EXTRACTOR_NOT_IN_NAMESPACE`: Collection uses extractor not in namespace\n- `MISSING_SECRET`: Secret reference not configured\n\n**Severity Levels:**\n- `error`: Must be fixed before applying\n- `warning`: Best practice violation, should be fixed\n- `info`: Suggestion for improvement\n\n**Example:**\n```bash\ncurl -X POST /v1/manifest/lint \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -F \"manifest_file=@mixpeek.yaml\"\n```\n\n**Response includes actionable suggestions:**\n```json\n{\n \"valid\": true,\n \"results\": [\n {\n \"code\": \"MISSING_CACHE_CONFIG\",\n \"severity\": \"warning\",\n \"message\": \"Retriever 'product_search' has no cache configuration\",\n \"location\": \"retrievers[0]\",\n \"suggestion\": \"Add cache_config to improve performance\",\n \"fix_example\": \"cache_config:\\n enabled: true\\n ttl_seconds: 3600\"\n }\n ],\n \"summary\": {\"error\": 0, \"warning\": 1, \"info\": 0}\n}\n```", "operationId": "lint_manifest_v1_manifest_lint_post", "parameters": [ { "name": "skip_rules", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Rule codes to skip (e.g., MISSING_DESCRIPTION)", "default": [], "title": "Skip Rules" }, "description": "Rule codes to skip (e.g., MISSING_DESCRIPTION)" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_lint_manifest_v1_manifest_lint_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LintResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/export": { "get": { "tags": [ "Manifest" ], "summary": "Export Manifest Get", "description": "Export current resources to a YAML manifest.\n\nExports all resources (or a specific namespace) to a YAML file\nthat can be version-controlled and re-applied to another environment.\n\n**Features:**\n- Resource IDs are converted to human-readable names\n- Secret values are replaced with placeholder references (`${{ secrets.NAME }}`)\n- Output is formatted for readability and git-friendliness\n\n**Note:** You must configure actual secrets before applying the exported\nmanifest to a new environment.\n\n**Example:**\n```bash\n# Export all resources\ncurl /v1/manifest/export \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -o mixpeek.yaml\n\n# Export specific namespace\ncurl \"/v1/manifest/export?namespace_id=ns_abc123\" \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -o namespace.yaml\n```", "operationId": "export_manifest_get_v1_manifest_export_get", "parameters": [ { "name": "namespace_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Export specific namespace (None = all)", "title": "Namespace Id" }, "description": "Export specific namespace (None = all)" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Output format (yaml)", "default": "yaml", "title": "Format" }, "description": "Output format (yaml)" }, { "name": "manifest_name", "in": "query", "required": false, "schema": { "type": "string", "description": "Name for the manifest", "default": "exported-manifest", "title": "Manifest Name" }, "description": "Name for the manifest" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Manifest" ], "summary": "Export Manifest Post", "description": "Export current resources to a YAML manifest (POST version for agent tools).\n\nSame as GET /export but accepts parameters in JSON body instead of query params.\nUsed by agent tools and programmatic API clients.\n\n**Example:**\n```bash\ncurl -X POST /v1/manifest/export \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"namespace_ids\": [\"ns_abc123\"], \"manifest_name\": \"my-setup\"}'\n```", "operationId": "export_manifest_post_v1_manifest_export_post", "parameters": [ { "name": "manifest_name", "in": "query", "required": false, "schema": { "type": "string", "default": "exported-manifest", "title": "Manifest Name" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "title": "Namespace Ids" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/diff": { "post": { "tags": [ "Manifest" ], "summary": "Diff Manifest", "description": "Compare a manifest file with current state.\n\nShows resources that would be:\n- **Created**: In manifest but not in system\n- **In system only**: In system but not in manifest\n- **Different**: In both but with configuration differences\n\nThis is useful for understanding what changes would occur\nbefore applying a manifest.\n\n**Example:**\n```bash\ncurl -X POST /v1/manifest/diff \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -F \"manifest_file=@mixpeek.yaml\"\n```", "operationId": "diff_manifest_v1_manifest_diff_post", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_diff_manifest_v1_manifest_diff_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/manifest/generate": { "post": { "tags": [ "Manifest" ], "summary": "Generate Manifest", "description": "Generate a manifest from natural language description.\n\n Uses AI to create a valid YAML manifest from a natural language description\n of desired resources. The generated manifest can be reviewed and applied.\n\n **Example:**\n ```bash\n curl -X POST /v1/manifest/generate \\\n -H \"Authorization: Bearer $API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"description\": \"I need a bucket of images that feeds into a multimodal extractor and a retriever\",\n \"manifest_name\": \"image-search-setup\"\n }'\n ```\n\n **Response:**\n ```json\n {\n \"manifest\": \"version: '1.0'\nmetadata:\n name: image-search-setup\n...\",\n \"format\": \"yaml\",\n \"manifest_name\": \"image-search-setup\",\n \"description\": \"I need a bucket of images...\"\n }\n ```\n\n **Next Steps:**\n 1. Review the generated manifest\n 2. Apply it using POST /v1/manifest/apply", "operationId": "generate_manifest_v1_manifest_generate_post", "parameters": [ { "name": "description", "in": "query", "required": true, "schema": { "type": "string", "title": "Description" } }, { "name": "manifest_name", "in": "query", "required": false, "schema": { "type": "string", "default": "generated-manifest", "title": "Manifest Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/discovery/extractors": { "get": { "tags": [ "Discovery" ], "summary": "List Available Feature Extractors", "description": "Discover all available feature extractors with their capabilities, supported modalities, output features, and example usage. Use this to understand what extractors are available when configuring namespaces and collections in manifests.", "operationId": "list_extractors_v1_discovery_extractors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ExtractorDiscovery" }, "type": "array", "title": "Response List Extractors V1 Discovery Extractors Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/discovery/stages": { "get": { "tags": [ "Discovery" ], "summary": "List Available Retriever Stages with Examples", "description": "Discover all available retriever stages with extended information including example configurations, common use cases, and cost tiers. This endpoint provides more context than /v1/retrievers/stages for agent-driven configuration.", "operationId": "list_stages_with_examples_v1_discovery_stages_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/StageDiscovery" }, "type": "array", "title": "Response List Stages With Examples V1 Discovery Stages Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/discovery/schema": { "get": { "tags": [ "Discovery" ], "summary": "Get Manifest Schema for Agent Configuration", "description": "Returns the complete manifest schema including all resource types, their JSON schemas, dependency graph, and YAML examples. Use this for programmatic manifest generation and validation.", "operationId": "get_manifest_schema_v1_discovery_schema_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestSchemaDiscovery" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/discovery": { "get": { "tags": [ "Discovery" ], "summary": "Get All Discovery Information", "description": "Returns combined discovery information including extractors, stages, and manifest schema in a single request. Use this for comprehensive capability discovery.", "operationId": "get_all_discovery_v1_discovery_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/marketplace/listings": { "post": { "tags": [ "Marketplace" ], "summary": "Create Marketplace Listing", "description": "Create a new marketplace listing for a retriever.\n\nThis endpoint allows retriever owners to publish their retrievers to the marketplace\nwith custom tiers, pricing, and display configuration.", "operationId": "create_marketplace_listing_v1_marketplace_listings_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Listing Data" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/marketplace/listings/{listing_id}": { "patch": { "tags": [ "Marketplace" ], "summary": "Update Marketplace Listing", "description": "Update an existing marketplace listing.", "operationId": "update_marketplace_listing_v1_marketplace_listings__listing_id__patch", "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Listing Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Listing Updates" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Marketplace" ], "summary": "Delete Marketplace Listing", "description": "Delete a marketplace listing.", "operationId": "delete_marketplace_listing_v1_marketplace_listings__listing_id__delete", "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Listing Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/marketplace/listings/{listing_id}/publish": { "patch": { "tags": [ "Marketplace" ], "summary": "Publish Marketplace Listing", "description": "Publish a marketplace listing (change status from draft to published).", "operationId": "publish_marketplace_listing_v1_marketplace_listings__listing_id__publish_patch", "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Listing Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/marketplace/catalog": { "get": { "tags": [ "Marketplace" ], "summary": "Browse Marketplace Catalog", "description": "Browse marketplace catalog with optional filters.\n\nReturns published, listed marketplace listings only. Unlisted retrievers\nare still accessible via direct link but don't appear here.", "operationId": "get_marketplace_catalog_v1_marketplace_catalog_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category (e.g., 'Content Moderation', 'Search')", "title": "Category" }, "description": "Filter by category (e.g., 'Content Moderation', 'Search')" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by tags (AND logic - listing must have all tags)", "title": "Tags" }, "description": "Filter by tags (AND logic - listing must have all tags)" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search in title and description", "title": "Search" }, "description": "Search in title and description" }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of listings to skip", "default": 0, "title": "Skip" }, "description": "Number of listings to skip" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of listings to return", "default": 20, "title": "Limit" }, "description": "Number of listings to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListing" }, "title": "Response Get Marketplace Catalog V1 Marketplace Catalog Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/marketplace/catalog/{public_name}": { "get": { "tags": [ "Marketplace" ], "summary": "Get Marketplace Listing by Public Name", "description": "Get detailed information about a marketplace listing by its public name.\n\nExample: /marketplace/catalog/brand-safety-api", "operationId": "get_marketplace_listing_by_name_v1_marketplace_catalog__public_name__get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public URL slug for the listing", "title": "Public Name" }, "description": "Public URL slug for the listing" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/marketplace/catalog/{public_name}/execute": { "post": { "tags": [ "Marketplace" ], "summary": "Execute Marketplace Retriever", "description": "Execute a marketplace retriever using its public name. Free tier listings can be accessed without authentication. Paid tier access requires a subscription token.", "operationId": "execute_marketplace_retriever_v1_marketplace_catalog__public_name__execute_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the marketplace listing", "title": "Public Name" }, "description": "Public name of the marketplace listing" }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage", "default": true, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage" }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include vector embeddings in response", "default": false, "title": "Return Vectors" }, "description": "Include vector embeddings in response" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverExecutionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/marketplace/catalog/{public_name}/config": { "get": { "tags": [ "Marketplace" ], "summary": "Get Marketplace Listing Configuration", "description": "Get display configuration for rendering the marketplace listing interface", "operationId": "get_marketplace_listing_config_v1_marketplace_catalog__public_name__config_get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the marketplace listing", "title": "Public Name" }, "description": "Public name of the marketplace listing" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/marketplace/catalog/{public_name}/verify": { "post": { "tags": [ "Marketplace" ], "summary": "Verify Password for Marketplace Listing", "description": "Verify password for a password-protected marketplace listing", "operationId": "verify_marketplace_listing_password_v1_marketplace_catalog__public_name__verify_post", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the marketplace listing", "title": "Public Name" }, "description": "Public name of the marketplace listing" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_verify_marketplace_listing_password_v1_marketplace_catalog__public_name__verify_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/marketplace/catalog/{public_name}/template": { "get": { "tags": [ "Marketplace" ], "summary": "Get Marketplace Listing as Template", "description": "Get the retriever configuration from a marketplace listing as a reusable template", "operationId": "get_marketplace_listing_template_v1_marketplace_catalog__public_name__template_get", "parameters": [ { "name": "public_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Public name of the marketplace listing", "title": "Public Name" }, "description": "Public name of the marketplace listing" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/v1/marketplace/subscriptions": { "post": { "tags": [ "Marketplace" ], "summary": "Subscribe to Marketplace Listing", "description": "Subscribe to a marketplace listing.\n\nFree Tier:\n - Immediately active\n - Returns access_token (prk_xxx format)\n - No Stripe checkout required\n\nPaid Tiers:\n - Creates pending subscription\n - Returns checkout_url for Stripe payment\n - Subscription activates after payment via webhook", "operationId": "create_subscription_v1_marketplace_subscriptions_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_create_subscription_v1_marketplace_subscriptions_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Create Subscription V1 Marketplace Subscriptions Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Marketplace" ], "summary": "List My Subscriptions", "description": "List all subscriptions for the current organization.", "operationId": "list_my_subscriptions_v1_marketplace_subscriptions_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionStatus" }, { "type": "null" } ], "description": "Filter by subscription status", "title": "Status" }, "description": "Filter by subscription status" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List My Subscriptions V1 Marketplace Subscriptions Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/marketplace/subscriptions/{subscription_id}": { "get": { "tags": [ "Marketplace" ], "summary": "Get Subscription Details", "description": "Get detailed information about a subscription.", "operationId": "get_subscription_v1_marketplace_subscriptions__subscription_id__get", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription ID", "title": "Subscription Id" }, "description": "Subscription ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Subscription V1 Marketplace Subscriptions Subscription Id Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Marketplace" ], "summary": "Cancel Subscription", "description": "Cancel a marketplace subscription.\n\nFree Tier: Immediately revokes access\nPaid Tiers: Cancels at end of billing period", "operationId": "cancel_subscription_v1_marketplace_subscriptions__subscription_id__delete", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Subscription ID to cancel", "title": "Subscription Id" }, "description": "Subscription ID to cancel" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Subscription V1 Marketplace Subscriptions Subscription Id Delete" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/": { "post": { "tags": [ "Namespace Migrations" ], "summary": "Create Migration", "description": "Create a new namespace migration.\n\nThis endpoint creates a migration and optionally validates it.\nUse start_immediately=True to begin execution immediately.\n\nArgs:\n request: FastAPI request\n create_request: Migration configuration\n\nReturns:\n CreateMigrationResponse with migration ID and status", "operationId": "create_migration_v1_namespaces_migrations__post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMigrationRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMigrationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/{migration_id}": { "get": { "tags": [ "Namespace Migrations" ], "summary": "Get Migration", "description": "Get migration details and status.\n\nArgs:\n request: FastAPI request\n migration_id: Migration ID\n\nReturns:\n GetMigrationResponse with full migration details", "operationId": "get_migration_v1_namespaces_migrations__migration_id__get", "parameters": [ { "name": "migration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Migration Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMigrationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Namespace Migrations" ], "summary": "Delete Migration", "description": "Delete a migration record.\n\nOnly draft, completed, failed, or cancelled migrations can be deleted.\n\nArgs:\n request: FastAPI request\n migration_id: Migration ID", "operationId": "delete_migration_v1_namespaces_migrations__migration_id__delete", "parameters": [ { "name": "migration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Migration Id" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/list": { "post": { "tags": [ "Namespace Migrations" ], "summary": "List Migrations", "description": "List migrations with optional filters.\n\nArgs:\n request: FastAPI request\n list_request: Filter and pagination parameters\n\nReturns:\n ListMigrationsResponse with migrations list", "operationId": "list_migrations_v1_namespaces_migrations_list_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMigrationsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMigrationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/{migration_id}/start": { "post": { "tags": [ "Namespace Migrations" ], "summary": "Start Migration", "description": "Start a migration execution.\n\nArgs:\n request: FastAPI request\n migration_id: Migration ID\n start_request: Start options\n\nReturns:\n StartMigrationResponse with task ID", "operationId": "start_migration_v1_namespaces_migrations__migration_id__start_post", "parameters": [ { "name": "migration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Migration Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMigrationRequest", "default": { "force": false } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMigrationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/{migration_id}/cancel": { "post": { "tags": [ "Namespace Migrations" ], "summary": "Cancel Migration", "description": "Cancel a running migration.\n\nArgs:\n request: FastAPI request\n migration_id: Migration ID\n cancel_request: Cancellation options\n\nReturns:\n CancelMigrationResponse with updated status", "operationId": "cancel_migration_v1_namespaces_migrations__migration_id__cancel_post", "parameters": [ { "name": "migration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Migration Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelMigrationRequest", "default": {} } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelMigrationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/migrations/validate": { "post": { "tags": [ "Namespace Migrations" ], "summary": "Validate Migration", "description": "Validate a migration configuration without creating it.\n\nUse this endpoint to check if a migration configuration is valid\nbefore actually creating and running it.\n\nArgs:\n request: FastAPI request\n validate_request: Configuration to validate\n\nReturns:\n ValidateMigrationResponse with validation results", "operationId": "validate_migration_v1_namespaces_migrations_validate_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateMigrationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateMigrationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/snapshots": { "post": { "tags": [ "Namespace Snapshots" ], "summary": "Create Namespace Snapshot", "description": "Create a point-in-time snapshot of the entire namespace. Captures all MongoDB documents and an S3 object manifest. Optionally copies S3 objects to the snapshot prefix for full data preservation (required if you plan to delete the namespace and restore later).", "operationId": "create_snapshot_v1_namespaces__namespace_identifier__snapshots_post", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/snapshots/list": { "post": { "tags": [ "Namespace Snapshots" ], "summary": "List Namespace Snapshots", "description": "List all snapshots for a namespace, newest first.", "operationId": "list_snapshots_v1_namespaces__namespace_identifier__snapshots_list_post", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSnapshotsRequest", "description": "Pagination parameters", "default": { "skip": 0, "limit": 20 } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSnapshotsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/snapshots/{snapshot_id}": { "get": { "tags": [ "Namespace Snapshots" ], "summary": "Get Snapshot", "description": "Get details of a specific snapshot.", "operationId": "get_snapshot_v1_namespaces__namespace_identifier__snapshots__snapshot_id__get", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot ID (e.g. snap_xxxxxxxxxxxx)", "title": "Snapshot Id" }, "description": "Snapshot ID (e.g. snap_xxxxxxxxxxxx)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Namespace Snapshots" ], "summary": "Delete Snapshot", "description": "Delete a snapshot and its associated S3 data.", "operationId": "delete_snapshot_v1_namespaces__namespace_identifier__snapshots__snapshot_id__delete", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot ID to delete", "title": "Snapshot Id" }, "description": "Snapshot ID to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/snapshots/{snapshot_id}/verify": { "get": { "tags": [ "Namespace Snapshots" ], "summary": "Verify Snapshot Restore-Readiness", "description": "Read-only pre-flight check that a snapshot can actually be restored. Restore is lenient and silently skips missing artifacts, so this surfaces what a restore would drop (missing collection dumps, unreachable vectors, absent copied objects) BEFORE you depend on it in a recovery. Pass deep=true to also decompress each collection dump and detect truncation.", "operationId": "verify_snapshot_v1_namespaces__namespace_identifier__snapshots__snapshot_id__verify_get", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot ID to verify (e.g. snap_xxxxxxxxxxxx)", "title": "Snapshot Id" }, "description": "Snapshot ID to verify (e.g. snap_xxxxxxxxxxxx)" }, { "name": "deep", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also decompress each collection dump to detect truncated artifacts", "default": false, "title": "Deep" }, "description": "Also decompress each collection dump to detect truncated artifacts" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotVerifyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/snapshots/{snapshot_id}/restore": { "post": { "tags": [ "Namespace Snapshots" ], "summary": "Restore From Snapshot", "description": "Restore a namespace from a snapshot. If target_namespace_name is provided, creates a new namespace with the restored data. Otherwise, restores in-place (replaces current namespace data).", "operationId": "restore_snapshot_v1_namespaces__namespace_identifier__snapshots__snapshot_id__restore_post", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID", "title": "Namespace Identifier" }, "description": "Namespace name or ID" }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot ID to restore from", "title": "Snapshot Id" }, "description": "Snapshot ID to restore from" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSnapshotRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSnapshotResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/clone": { "post": { "tags": [ "Namespace Clone" ], "summary": "Clone Namespace", "description": "Clone a namespace with all its data.\n\n **What gets cloned:**\n - Namespace configuration (extractors, payload indexes)\n - Buckets (metadata, references same S3 files)\n - Collections (full copy of all vectors/embeddings)\n - Retrievers (pipeline configuration)\n\n **Use Cases:**\n - Create staging environment from production\n - Backup namespace with all data\n - Fork namespace for experimentation\n\n **For config-only copy (no data), use templates instead:**\n - POST /templates/namespaces/from-namespace/{id}\n - POST /templates/namespaces/{template_id}/instantiate", "operationId": "clone_namespace_v1_namespaces__namespace_identifier__clone_post", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Source namespace ID or name to clone from", "title": "Namespace Identifier" }, "description": "Source namespace ID or name to clone from" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneNamespaceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneNamespaceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces": { "post": { "tags": [ "Namespaces" ], "summary": "Create Namespace", "description": "Creates a new namespace with specified feature extractors and payload indexes.", "operationId": "create_namespace_v1_namespaces_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNamespaceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Namespaces" ], "summary": "List Namespaces", "description": "List all namespaces (GET alias for POST /list). Supports query param pagination: ?limit=N&offset=M", "operationId": "list_namespaces_get_v1_namespaces_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNamespacesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}": { "delete": { "tags": [ "Namespaces" ], "summary": "Delete Namespace", "description": "This endpoint deletes a namespace and ALL its resources including:\n - All buckets (with S3 objects, batches, uploads)\n - All collections (with Qdrant points, cache, webhooks)\n - All clusters (with Ray jobs, executions, triggers, S3 artifacts)\n - All retrievers (with executions, evaluations, interactions, cache)\n - Remaining MongoDB collections (tasks, uploads, taxonomies, API keys, etc.)\n - All S3 objects with namespace prefix\n - Qdrant collection (namespace's vector database)\n - All namespace cache (across all scopes)\n - Analytics data (ClickHouse tables)\n - Namespace metadata\n\n The deletion is performed asynchronously. Returns a task_id that can be used\n to poll for deletion progress via GET /v1/tasks/{task_id}.\n\n \u26a0\ufe0f WARNING: This operation is irreversible and will delete ALL data in the namespace!", "operationId": "delete_namespace_v1_namespaces__namespace_identifier__delete", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force deletion even if batches are still processing. Without this flag, the endpoint returns 409 when active batches exist.", "default": false, "title": "Force" }, "description": "Force deletion even if batches are still processing. Without this flag, the endpoint returns 409 when active batches exist." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "tags": [ "Namespaces" ], "summary": "Update Namespace", "description": "Fully updates an existing namespace (all fields required)", "operationId": "update_namespace_v1_namespaces__namespace_identifier__put", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNamespaceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Namespaces" ], "summary": "Partially Update Namespace", "description": "Partially updates an existing namespace (PATCH operation)", "operationId": "patch_namespace_v1_namespaces__namespace_identifier__patch", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchNamespaceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Namespaces" ], "summary": "Get Namespace", "description": "Retrieve details of a specific namespace using either its name or ID", "operationId": "get_namespace_v1_namespaces__namespace_identifier__get", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/list": { "post": { "tags": [ "Namespaces" ], "summary": "List Namespaces", "description": "List all namespaces for a user", "operationId": "list_namespaces_v1_namespaces_list_post", "parameters": [ { "name": "include_system", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include read-only system namespaces (e.g. sample-data)", "default": false, "title": "Include System" }, "description": "Include read-only system namespaces (e.g. sample-data)" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "full", "summary" ], "type": "string", "description": "Response detail level. 'full' (default) returns complete namespace objects. 'summary' omits heavy per-namespace config (payload_indexes, feature_extractors, vector_inference_map, vector_configs) \u2014 ~93% smaller \u2014 for high-frequency list/switcher views. Fetch full config via GET /v1/namespaces/{namespace_identifier}.", "default": "full", "title": "View" }, "description": "Response detail level. 'full' (default) returns complete namespace objects. 'summary' omits heavy per-namespace config (payload_indexes, feature_extractors, vector_inference_map, vector_configs) \u2014 ~93% smaller \u2014 for high-frequency list/switcher views. Fetch full config via GET /v1/namespaces/{namespace_identifier}." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNamespacesRequest", "default": { "case_sensitive": false } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNamespacesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/stats/batch": { "post": { "tags": [ "Namespaces" ], "summary": "Get Namespace Stats (Batch)", "description": "Returns document/bucket/collection/object counts for many namespaces in ONE call. Replaces per-row /stats fan-out on list views. Counts are aggregated in batch and live doc-counts gathered concurrently; namespaces the caller cannot see are omitted.", "operationId": "get_namespace_stats_batch_v1_namespaces_stats_batch_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceStatsBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceStatsBatchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/stats": { "get": { "tags": [ "Namespaces" ], "summary": "Get Namespace Stats", "description": "Returns document, bucket, collection, and object counts for a single namespace. Use this instead of relying on counts in the list endpoint.", "operationId": "get_namespace_stats_v1_namespaces__namespace_identifier__stats_get", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceStatsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_identifier}/ensure-indexes": { "post": { "tags": [ "Namespaces" ], "summary": "Ensure Namespace Payload Indexes", "description": "(Re-)create the namespace's declared payload indexes in the vector store, including FULLTEXT/BM25, idempotently. ZERO-EXTRACTION: registers any missing indexes and backfills existing documents WITHOUT triggering any ingest or re-extraction. Use to repair a missing index (e.g. a FULLTEXT index that failed to register) or as a self-serve re-index tool \u2014 no re-ingest, no GPU.\n\nREADING THE RESPONSE: `ensured` lists indexes the call confirmed present \u2014 it does NOT mean they were newly built, and an already-registered index is a cheap no-op on the shard. `rebuilt` is populated only with `force_rebuild=true`, which is the case that does real work. `skipped` is normally empty because the store reports an idempotent no-op as success rather than an error, so an empty `skipped` does not imply the rest were created. `created` is a deprecated alias of `ensured` + `rebuilt`.\n\nCOST: a plain ensure is cheap. `force_rebuild=true` applies to EVERY declared index, drops and rebuilds each from the complete store, and for FULLTEXT fields first hydrates the full payload store \u2014 no GPU, but real shard CPU and memory proportional to the corpus. Size it before running on a large or memory-constrained namespace.", "operationId": "ensure_namespace_indexes_v1_namespaces__namespace_identifier__ensure_indexes_post", "parameters": [ { "name": "namespace_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the namespace name or namespace ID", "examples": [ "my_namespace", "ns_1234567890" ], "title": "Namespace Identifier" }, "description": "Either the namespace name or namespace ID" }, { "name": "force_rebuild", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop and rebuild each index from the complete store instead of the normal idempotent ensure. Use to repair a FULLTEXT/BM25 field that registered empty during a cold shard warmup (no cluster access needed \u2014 the shard grpc is in-cluster only, so this API is the sole trigger). Default false.", "default": false, "title": "Force Rebuild" }, "description": "Drop and rebuild each index from the complete store instead of the normal idempotent ensure. Use to repair a FULLTEXT/BM25 field that registered empty during a cold shard warmup (no cluster access needed \u2014 the shard grpc is in-cluster only, so this API is the sole trigger). Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/documents/upsert": { "post": { "tags": [ "BYO Documents" ], "summary": "Upsert documents with BYO vectors", "description": "Upsert documents with user-provided vectors directly into a namespace. This bypasses the collection/batch/extractor pipeline entirely. Documents go directly to the vector store. Maximum 1000 documents per call.", "operationId": "upsert_documents_byo_v1_namespaces__namespace_id__documents_upsert_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The namespace to upsert documents into.", "examples": [ "ns_abc123def456" ], "title": "Namespace Id" }, "description": "The namespace to upsert documents into." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOUpsertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BYOUpsertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/documents/{document_id}": { "get": { "tags": [ "BYO Documents" ], "summary": "Get a document by ID (path-scoped namespace)", "description": "Fetch a single document by document_id from a namespace named in the PATH \u2014 the mirror of POST /v1/namespaces/{namespace_id}/documents/upsert, so directly-upserted (BYO/standalone) documents can be read back on the same URL convention they were written with. Equivalent to GET /v1/documents/{document_id} with the X-Namespace header.", "operationId": "get_document_byo_v1_namespaces__namespace_id__documents__document_id__get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace name or ID the document lives in.", "examples": [ "ns_abc123def456" ], "title": "Namespace Id" }, "description": "Namespace name or ID the document lives in." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The document_id to fetch.", "examples": [ "doc_001" ], "title": "Document Id" }, "description": "The document_id to fetch." }, { "name": "return_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Return Vectors" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/standalone": { "post": { "tags": [ "BYO Documents" ], "summary": "Create standalone namespace (BYO vectors)", "description": "Create a standalone namespace for BYO (Bring Your Own) vectors. No collection or feature extractor binding is required. Users upsert pre-computed vectors directly via the direct upsert endpoint.", "operationId": "create_standalone_namespace_v1_namespaces_standalone_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStandaloneNamespaceRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandaloneNamespaceResponseModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/promote": { "post": { "tags": [ "BYO Documents" ], "summary": "Promote standalone namespace to managed mode", "description": "Promote a standalone (BYO vectors) namespace to managed mode. Existing vectors and documents are preserved. Optionally maps existing vector indexes to inference services and adds new indexes.", "operationId": "promote_namespace_v1_namespaces__namespace_id__promote_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace to promote", "title": "Namespace Id" }, "description": "Namespace to promote" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteNamespaceRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteNamespaceResponseModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/promote/validate": { "post": { "tags": [ "BYO Documents" ], "summary": "Dry-run validate a standalone \u2192 managed promotion", "description": "Validate a proposed promotion without mutating the namespace. Returns per-index mapping suggestions (dimension-matched candidates, flagged low-confidence) and validates any supplied vector_mappings / add_vectors for unknown indexes, unknown inference services, and dimension mismatches. Returns HTTP 422 when supplied mappings are invalid so callers can fix them before the real promote call.", "operationId": "validate_promotion_v1_namespaces__namespace_id__promote_validate_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Namespace to validate promotion for", "title": "Namespace Id" }, "description": "Namespace to validate promotion for" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteNamespaceRequestModel" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteValidateResponseModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/{extractor_id}/publish": { "post": { "tags": [ "Extractor Publishing" ], "summary": "Publish an extractor to the marketplace", "operationId": "publish_extractor_v1_extractors__extractor_id__publish_post", "parameters": [ { "name": "extractor_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the extractor to publish", "title": "Extractor Id" }, "description": "ID of the extractor to publish" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishExtractorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishExtractorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Extractor Publishing" ], "summary": "Get published extractor status", "operationId": "get_published_extractor_v1_extractors__extractor_id__publish_get", "parameters": [ { "name": "extractor_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the extractor", "title": "Extractor Id" }, "description": "ID of the extractor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedExtractorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Extractor Publishing" ], "summary": "Update published extractor", "operationId": "update_published_extractor_v1_extractors__extractor_id__publish_patch", "parameters": [ { "name": "extractor_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the extractor", "title": "Extractor Id" }, "description": "ID of the extractor" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublishedExtractorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedExtractorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Extractor Publishing" ], "summary": "Unpublish an extractor", "operationId": "unpublish_extractor_v1_extractors__extractor_id__publish_delete", "parameters": [ { "name": "extractor_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the extractor to unpublish", "title": "Extractor Id" }, "description": "ID of the extractor to unpublish" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/install": { "post": { "tags": [ "Extractor Publishing" ], "summary": "Install a public extractor", "operationId": "install_extractor_v1_extractors_install_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallExtractorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallExtractorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors": { "get": { "tags": [ "Extractors" ], "summary": "List all extractors available to organization", "description": "List all extractors available across the organization.\n\nReturns a unified view combining:\n- **Builtin extractors**: Core extractors shipped with Mixpeek\n- **Custom extractors**: Org-level custom extractors (uploaded via the upload workflow)\n\nUse `source` to filter by origin.", "operationId": "list_org_extractors_v1_extractors_get", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "builtin", "custom", "all" ], "type": "string" }, { "type": "null" } ], "description": "Filter by extractor source", "title": "Source" }, "description": "Filter by extractor source" }, { "name": "include_disabled", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include disabled/undeployed custom extractors", "default": false, "title": "Include Disabled" }, "description": "Include disabled/undeployed custom extractors" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedExtractorListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/submissions/uploads": { "post": { "tags": [ "Extractors" ], "summary": "Get presigned URL for extractor submission", "description": "Step 1: Get a presigned URL to upload your extractor archive to S3.", "operationId": "generate_upload_url_v1_extractors_submissions_uploads_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubmissionUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionPresignedURLResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/submissions/uploads/{submission_id}/confirm": { "post": { "tags": [ "Extractors" ], "summary": "Confirm extractor submission upload", "description": "Step 2: Confirm upload, triggers security scan and manifest validation.", "operationId": "confirm_submission_v1_extractors_submissions_uploads__submission_id__confirm_post", "parameters": [ { "name": "submission_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Submission Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmSubmissionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmSubmissionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/submissions": { "get": { "tags": [ "Extractors" ], "summary": "List extractor submissions", "description": "List all extractor submissions for this organization.", "operationId": "list_submissions_v1_extractors_submissions_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "submitted", "scanning", "review", "approved", "rejected" ], "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/extractors/submissions/{submission_id}": { "get": { "tags": [ "Extractors" ], "summary": "Get submission details", "operationId": "get_submission_v1_extractors_submissions__submission_id__get", "parameters": [ { "name": "submission_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Submission Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/models/uploads": { "post": { "tags": [ "Models" ], "summary": "Generate presigned URL for model upload", "description": "Generate a presigned URL for uploading a custom model archive.\n\nThis is step 1 of the presigned URL workflow:\n1. POST /models/uploads \u2192 Returns presigned_url + upload_id\n2. PUT presigned_url with model archive (client uploads directly to S3)\n3. POST /models/uploads/{upload_id}/confirm \u2192 Validates and creates model\n\nThe model will be stored at the organization level and can be enabled\nin any namespace within the organization.\n\n**Availability**: custom model upload is an **enterprise-tier** feature \u2014\nrequests from other account tiers receive a 403. Contact support or\nupgrade your plan to enable it (BACKE-2759: this gate was previously\nundocumented and only discoverable by hitting the 403).", "operationId": "generate_upload_url_v1_models_uploads_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPresignedURLResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/models/uploads/{upload_id}/confirm": { "post": { "tags": [ "Models" ], "summary": "Confirm model upload", "description": "Confirm a model upload after the S3 upload completes.\n\nThis is step 3 of the presigned URL workflow. Call this after\nuploading the model archive to the presigned URL.\n\nThe service will:\n1. Verify the S3 object exists\n2. Validate the archive structure\n3. Create the model record", "operationId": "confirm_upload_v1_models_uploads__upload_id__confirm_post", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmModelUploadRequest", "default": {} } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmModelUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List organization models", "description": "List all custom models registered at the organization level.\n\nThese models can be enabled in any namespace within the organization\nusing the namespace-level enable endpoint.", "operationId": "list_models_v1_models_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgModelListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/models/{model_id}": { "get": { "tags": [ "Models" ], "summary": "Get model details", "description": "Get detailed information about an org-level model.", "operationId": "get_model_v1_models__model_id__get", "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgModelDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Models" ], "summary": "Delete model", "description": "Delete an org-level model.\n\nThe model must not be enabled in any namespaces. If it is still enabled,\nyou must disable it in all namespaces first before deleting.", "operationId": "delete_model_v1_models__model_id__delete", "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgModelDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/models/{model_id}/download": { "get": { "tags": [ "Models" ], "summary": "Download model archive", "description": "Get a presigned download URL for a model's archive (.tar.gz).\n\nOnly available for exportable models. Models created by Mixpeek\nprofessional services (source='mixpeek') are non-exportable and will\nreturn 403.", "operationId": "download_model_v1_models__model_id__download_get", "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Download Model V1 Models Model Id Download Get" }, "example": { "download_url": "https://s3.amazonaws.com/..." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Model is non-exportable" }, "404": { "description": "Model not found" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/extractors": { "get": { "tags": [ "Namespace Extractors" ], "summary": "List all extractors available to namespace", "description": "List all feature extractors available for use in this namespace.\n\nThis endpoint returns a **unified view** combining:\n- **Builtin extractors**: Core extractors shipped with Mixpeek (text_extractor, image_extractor, etc.)\n- **Custom plugins**: User-uploaded plugins at org or namespace level (Enterprise)\n\nEach extractor includes:\n- `input_schema`: JSON schema for input data validation\n- `output_schema`: JSON schema for output document structure\n- `parameter_schema`: JSON schema for configurable parameters\n- `required_vector_indexes`: Vector indexes produced by this extractor\n- `feature_uri`: URI to reference this extractor in collections\n\n**Use Cases:**\n- Discover available extractors when creating collections\n- Get schema information for SDK code generation\n- Check which custom plugins are deployed\n\n**Filtering:**\n- `source=builtin`: Only builtin extractors\n- `source=custom`: Only custom plugins\n- `source=all` (default): All extractors", "operationId": "list_extractors_v1_namespaces__namespace_id__extractors_get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "builtin", "custom", "all" ], "type": "string" }, { "type": "null" } ], "description": "Filter by extractor source (builtin, custom, or all)", "title": "Source" }, "description": "Filter by extractor source (builtin, custom, or all)" }, { "name": "include_disabled", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include disabled/undeployed custom plugins", "default": false, "title": "Include Disabled" }, "description": "Include disabled/undeployed custom plugins" } ], "responses": { "200": { "description": "List of all available extractors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedExtractorListResponse" }, "example": { "success": true, "extractors": [ { "feature_extractor_name": "text_extractor", "version": "v1", "feature_extractor_id": "text_extractor_v1", "source": "builtin", "description": "Extract text embeddings from documents", "input_schema": { "type": "object" }, "output_schema": { "type": "object" }, "feature_uri": "mixpeek://text_extractor@v1/embedding" } ], "total": 8, "namespace_id": "ns_xxx", "builtin_count": 6, "custom_count": 2 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/namespaces/{namespace_id}/extractors/{extractor_id}": { "get": { "tags": [ "Namespace Extractors" ], "summary": "Get extractor details", "description": "Get detailed information about a specific extractor.\n\nWorks for both builtin extractors and custom plugins.\n\n**Parameters:**\n- `extractor_id`: Extractor identifier (e.g., 'text_extractor_v1', 'my_custom_plugin_1_0_0')\n\n**Response includes:**\n- Full schema information (input, output, parameters)\n- Vector index configuration\n- For custom plugins: deployment status, validation status", "operationId": "get_extractor_v1_namespaces__namespace_id__extractors__extractor_id__get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "extractor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Extractor Id" } } ], "responses": { "200": { "description": "Extractor details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedExtractorResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Extractor not found", "content": { "application/json": { "example": { "detail": "Extractor 'unknown_extractor_v1' not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/namespaces/{namespace_id}/models": { "post": { "tags": [ "Custom Models" ], "summary": "Upload a custom model", "description": "Upload custom model weights to the namespace.\n\n**Requirements:**\n- Organization must be on Enterprise tier\n\n**Supported Model Formats:**\n- `safetensors`: SafeTensors format (recommended for transformers)\n- `onnx`: ONNX Runtime format\n- `pytorch`: PyTorch state_dict or TorchScript\n- `huggingface`: HuggingFace model directory\n\n**Base Images (auto-selected based on format):**\n- `mixpeek/serve-gpu:latest`: For safetensors, pytorch, huggingface (includes torch, transformers)\n- `mixpeek/serve-minimal:latest`: For ONNX (includes onnxruntime only)\n\n**Important:** Models run in fixed base images. You cannot install additional pip packages.\nAll required frameworks (torch, transformers, onnxruntime) are pre-installed.", "operationId": "upload_model_v1_namespaces__namespace_id__models_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_model_v1_namespaces__namespace_id__models_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Custom models not supported" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Model already exists" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Custom Models" ], "summary": "List models in namespace", "description": "List all custom models uploaded to the namespace.", "operationId": "list_models_v1_namespaces__namespace_id__models_get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/models/available": { "get": { "tags": [ "Custom Models" ], "summary": "List available org models", "description": "List org-level models available to enable in this namespace.\n\nShows all models registered at the organization level and whether\nthey are already enabled in the target namespace.", "operationId": "list_available_org_models_v1_namespaces__namespace_id__models_available_get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableOrgModelsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/models/org/{model_id}/enable": { "post": { "tags": [ "Custom Models" ], "summary": "Enable org model for namespace", "description": "Enable an org-level model for this namespace.\n\nThis creates a namespace-specific deployment record for the model,\nallowing it to be used within this namespace. Optionally deploys\nthe model to Ray immediately.\n\n**Note:** The model must first be registered at the organization level\nvia POST /models/uploads.", "operationId": "enable_org_model_v1_namespaces__namespace_id__models_org__model_id__enable_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableOrgModelRequest", "default": { "deploy": false } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableOrgModelResponse" } } } }, "400": { "description": "Model validation failed" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Org model not found" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/models/org/{model_id}/disable": { "post": { "tags": [ "Custom Models" ], "summary": "Disable org model for namespace", "description": "Disable an org-level model for this namespace.\n\nThis removes the namespace-specific deployment record. The model\nremains available at the organization level and can be re-enabled.", "operationId": "disable_org_model_v1_namespaces__namespace_id__models_org__model_id__disable_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableOrgModelResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not enabled in namespace" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/models/{model_id}": { "get": { "tags": [ "Custom Models" ], "summary": "Get model details", "description": "Get detailed information about a specific model.", "operationId": "get_model_v1_namespaces__namespace_id__models__model_id__get", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Custom Models" ], "summary": "Delete a model", "description": "Delete a custom model from the namespace.", "operationId": "delete_model_v1_namespaces__namespace_id__models__model_id__delete", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/namespaces/{namespace_id}/models/{model_id}/deploy": { "post": { "tags": [ "Custom Models" ], "summary": "Deploy model to Ray object store", "description": "Pre-load model weights into the Ray object store for fast access by plugins.\n\nThis operation:\n1. Downloads the model archive from S3\n2. Deserializes weights based on format (safetensors, pytorch, etc.)\n3. Stores weights in Ray object store for zero-copy sharing\n\nAfter deployment, plugins can load the model instantly using:\n```python\nfrom engine.models.loader import load_namespace_model\nweights = load_namespace_model(\"model_id\")\n```\n\n**Note:** This is optional - models are also loaded on-demand when plugins\nfirst request them. Use this endpoint to pre-warm the cache.", "operationId": "deploy_model_v1_namespaces__namespace_id__models__model_id__deploy_post", "parameters": [ { "name": "namespace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Namespace Id" } }, { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDeployResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Model not found" }, "500": { "description": "Deployment failed" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/buckets": { "post": { "tags": [ "Buckets" ], "summary": "Create Bucket", "description": "This endpoint allows you to create a new bucket with a defined schema.\n A bucket is a collection of objects that conform to the schema.\n The schema defines the structure and validation rules for objects in the bucket.", "operationId": "create_bucket_v1_buckets_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Buckets" ], "summary": "List Buckets", "description": "List buckets (GET alias for POST /buckets/list), so buckets can be listed the same way as collections, retrievers, and namespaces.", "operationId": "list_buckets_get_v1_buckets_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search over bucket names.", "title": "Search" }, "description": "Free-text search over bucket names." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBucketsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}": { "get": { "tags": [ "Buckets" ], "summary": "Get Bucket", "description": "This endpoint retrieves a bucket by its ID.", "operationId": "get_bucket_v1_buckets__bucket_identifier__get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "put": { "tags": [ "Buckets" ], "summary": "Update Bucket", "description": "This endpoint allows you to update an existing bucket.\n You can update the bucket's name, description, and metadata.", "operationId": "update_bucket_v1_buckets__bucket_identifier__put", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Buckets" ], "summary": "Partially Update Bucket", "description": "This endpoint allows you to partially update an existing bucket (PATCH operation).\n Only provided fields will be updated. At minimum, metadata can always be updated.\n Immutable fields like bucket_id and timestamps cannot be modified.", "operationId": "patch_bucket_v1_buckets__bucket_identifier__patch", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketPatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Buckets" ], "summary": "Delete Bucket", "description": "This endpoint deletes a bucket and all its resources including:\n - S3 objects and blobs\n - Running Ray jobs (cancels active batch processing jobs)\n - Batch processing artifacts\n - Upload files\n - Unique key lookups\n - MongoDB metadata\n\n The deletion is performed **asynchronously** via a background task.\n Returns immediately with a task_id that can be polled via GET /v1/tasks/{task_id}.\n\n **Response**:\n - `task_id`: Use this to poll deletion status via GET /v1/tasks/{task_id}\n - `status`: Initial status (PENDING)\n - `bucket_id`: The bucket being deleted\n - `bucket_name`: Name of the bucket\n - `object_count`: Number of objects that will be deleted\n\n **Polling**:\n Poll GET /v1/tasks/{task_id} until status is COMPLETED or FAILED.\n Use exponential backoff (start 1s, max 30s).", "operationId": "delete_bucket_v1_buckets__bucket_identifier__delete", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Identifier" } }, { "name": "force_foreclose", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Force Foreclose" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/list": { "post": { "tags": [ "Buckets" ], "summary": "List Buckets", "description": "This endpoint lists buckets with pagination, sorting, and filtering options.", "operationId": "list_buckets_v1_buckets_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBucketsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBucketsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Create Sync Configuration", "description": "Create a sync configuration for automated storage ingestion.\n\nEstablishes automated synchronization between an external storage provider\nand a Mixpeek bucket. The sync monitors the source path and ingests files\naccording to the specified mode and filters.\n\n**Supported Providers:** google_drive, s3, snowflake, sharepoint, tigris\n\n**Built-in Robustness:**\n- Dead Letter Queue (DLQ): Failed objects tracked with 3 retries\n- Idempotent ingestion: Deduplication prevents duplicate objects\n- Distributed locking: Prevents concurrent sync execution\n- Rate limit handling: Automatic backoff on 429 responses\n- Metrics: Duration, files synced/failed, batches created\n\n**Sync Modes** (the request enum accepts exactly these two):\n- `initial_only`: Single bulk import, then sync stops\n- `continuous`: Polling-based monitoring (``polling_interval_seconds``,\n max 900)\n\n(Docstring previously advertised ``one_time``/``scheduled``, which the\nenum rejects with a 422 \u2014 modes here must match ``SyncCreateRequest``.)", "operationId": "create_sync_configuration_v1_buckets__bucket_id__syncs_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConfigurationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/list": { "post": { "tags": [ "Bucket Syncs" ], "summary": "List Sync Configurations", "description": "List all sync configurations for a bucket with optional filtering.\n\nReturns paginated list of sync configurations with status, metrics, and settings.\nUse filters to find syncs by connection, status, or active state.", "operationId": "list_sync_configurations_v1_buckets__bucket_id__syncs_list_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSyncConfigurationsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}": { "get": { "tags": [ "Bucket Syncs" ], "summary": "Get Sync Configuration", "description": "Fetch a sync configuration.", "operationId": "get_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConfigurationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Bucket Syncs" ], "summary": "Update Sync Configuration", "description": "Update a sync configuration.", "operationId": "update_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__patch", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConfigurationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Bucket Syncs" ], "summary": "Delete Sync Configuration", "description": "Delete a sync configuration.", "operationId": "delete_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__delete", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/metrics": { "get": { "tags": [ "Bucket Syncs" ], "summary": "Get Sync Metrics", "description": "Operational metrics for a sync in one call.\n\nFolds config totals + health/staleness + the DLQ failure breakdown (grouped\nby normalized error reason) + the most-recent job's throughput into a single\nresponse \u2014 so callers can see \"is this sync healthy / is anything backlogged\"\nwithout stitching /jobs and /dlq or reading logs.", "operationId": "get_sync_metrics_v1_buckets__bucket_id__syncs__sync_config_id__metrics_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncMetricsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/pause": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Pause Sync Configuration", "description": "Pause a sync configuration.\n\nPauses the sync, preventing new sync jobs from executing.\nRunning jobs will complete but no new jobs will be scheduled.\nThe sync configuration and all settings are preserved.\n\n**Note:** Use POST /resume to reactivate the sync.", "operationId": "pause_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__pause_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConfigurationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/resume": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Resume Sync Configuration", "description": "Resume a paused sync configuration.\n\nReactivates a paused sync, allowing new sync jobs to be scheduled.\nFor continuous syncs, polling will resume at the configured interval.\nThe next sync will be incremental (only files modified since last sync).", "operationId": "resume_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__resume_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncConfigurationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/trigger": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Trigger Sync Configuration", "description": "Manually trigger a sync execution.\n\nCreates a sync job and immediately dispatches it for async execution via Celery.\nThe sync job processes files from the storage provider and creates objects in the bucket.\n\n**Execution Flow:**\n1. Acquires distributed lock (prevents concurrent runs)\n2. Iterates files from storage provider with configured filters\n3. Creates objects idempotently (skips duplicates)\n4. Failed objects go to Dead Letter Queue (3 retries)\n5. Creates batches for collection processing (100 objects/batch)\n6. Emits metrics and releases lock\n\n**Use Cases:**\n- Test sync configuration after creation\n- Force sync outside of scheduled intervals\n- Re-sync after updating connection credentials\n- Trigger incremental sync (only modified files)\n\n**Returns:** `sync_job_id` to track progress via GET /syncs/{id}", "operationId": "trigger_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__trigger_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } }, { "name": "full_sync", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Full Sync" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/unlock": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Force Unlock Sync Configuration", "description": "Force-release a distributed lock on a sync configuration.\n\nUse this when a sync trigger returns 'skipped_already_running' but no sync\nis actually executing (zombie lock from a crashed worker).", "operationId": "force_unlock_sync_configuration_v1_buckets__bucket_id__syncs__sync_config_id__unlock_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/jobs": { "post": { "tags": [ "Bucket Syncs" ], "summary": "List Sync Jobs", "description": "List sync job history for a sync configuration.\n\nReturns paginated job records ordered by most recent first.\nEach job includes status, file counts, timing, and error details.\nUse the optional status filter to find failed or running jobs.", "operationId": "list_sync_jobs_v1_buckets__bucket_id__syncs__sync_config_id__jobs_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSyncJobsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncJobListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/jobs/{sync_job_id}": { "get": { "tags": [ "Bucket Syncs" ], "summary": "Get Sync Job", "description": "Get details for a specific sync job.\n\nReturns the full job record including status, file counts,\nstart/completion times, and any error messages.", "operationId": "get_sync_job_v1_buckets__bucket_id__syncs__sync_config_id__jobs__sync_job_id__get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } }, { "name": "sync_job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncJobModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/dlq": { "post": { "tags": [ "Bucket Syncs" ], "summary": "List Dlq Entries", "description": "List Dead Letter Queue entries for a sync configuration.\n\nReturns objects that failed to sync after all retry attempts.\nEach entry includes the source object ID, error details, retry count,\nand timestamps. Use this to diagnose and resolve sync failures.", "operationId": "list_dlq_entries_v1_buckets__bucket_id__syncs__sync_config_id__dlq_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDLQRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DLQListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/dlq/requeue": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Requeue Dlq Entries", "description": "Return exhausted DLQ entries to the retry path (TG-2999).\n\nThe inverse of bulk-mark-failed. Use after fixing the underlying cause (a\nrestored proxy URL, a storage permission, an upstream outage) to re-drive the\nentries that gave up. Without this, the only way to re-drive a DLQ was to\nlean on natural sync-diff and hope the objects were rediscovered.\n\nResets `max_retries_reached` and `retry_count`, stamps `requeued_at`, and\nclears `disposal_reason` so the retry task does not immediately re-retire the\nentry. Only entries that have EXHAUSTED their retries are touched; anything\nstill retrying is left alone rather than silently granted extra attempts.\n\nOmit `error_types` to requeue everything exhausted for the sync config.", "operationId": "requeue_dlq_entries_v1_buckets__bucket_id__syncs__sync_config_id__dlq_requeue_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequeueDLQRequest", "default": {} } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRequeueDLQResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_id}/syncs/{sync_config_id}/dlq/bulk-mark-failed": { "post": { "tags": [ "Bucket Syncs" ], "summary": "Bulk Mark Dlq Permanently Failed", "description": "Mark DLQ entries as permanently failed by error type.\n\nStops automatic retries for entries matching the specified error types.\nUse this for structurally unrecoverable errors (e.g. missing proxy URLs,\nunsupported file types) that will never succeed on retry.", "operationId": "bulk_mark_dlq_permanently_failed_v1_buckets__bucket_id__syncs__sync_config_id__dlq_bulk_mark_failed_post", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sync Config Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkMarkDLQRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkMarkDLQResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects": { "post": { "tags": [ "Bucket Objects" ], "summary": "Create Object", "description": "This endpoint creates a new object in the specified bucket.\n The object must conform to the bucket's schema.\n\n **Processing**: By default, objects are created in DRAFT status and require\n batch submission for processing. Set `auto_process=true` to automatically\n create a batch and submit it for processing (zero-touch workflow).\n\n If the bucket has a unique_key configured, the insertion policy determines behavior:\n - insert: Create only. Fail with 409 Conflict if unique key exists.\n - update: Update only. Fail with 404 Not Found if unique key doesn't exist.\n - upsert: Create if new, update if exists (idempotent).\n\n Policy resolution:\n 1. Use ?policy= query parameter if provided\n 2. Fall back to bucket's default_policy if configured\n 3. Error 400 if neither is specified", "operationId": "create_object_v1_buckets__bucket_identifier__objects_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "policy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Insertion policy for unique key enforcement. Valid values: 'insert', 'update', 'upsert'. Only applies if bucket has unique_key configured. Overrides bucket's default_policy if provided.", "examples": [ "insert", "update", "upsert" ], "title": "Policy" }, "description": "Insertion policy for unique key enforcement. Valid values: 'insert', 'update', 'upsert'. Only applies if bucket has unique_key configured. Overrides bucket's default_policy if provided." }, { "name": "auto_process", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically create a batch and submit it for processing. When true, the object will be immediately queued for processing without requiring separate batch creation and submission calls. Ideal for onboarding and single-object workflows.", "default": false, "title": "Auto Process" }, "description": "Automatically create a batch and submit it for processing. When true, the object will be immediately queued for processing without requiring separate batch creation and submission calls. Ideal for onboarding and single-object workflows." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Bucket Objects" ], "summary": "List Objects (GET)", "description": "List objects in a bucket via GET with cursor-based pagination. Use POST /list for filtering and sorting.", "operationId": "list_objects_get_v1_buckets__bucket_identifier__objects_get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListObjectsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects/batch": { "post": { "tags": [ "Bucket Objects" ], "summary": "Create Objects in Batch", "description": "This endpoint creates multiple new objects in the specified bucket as a batch.\n Each object must conform to the bucket's schema.\n\n **Processing**: By default, objects are created in DRAFT status and require\n batch submission for processing. Set `auto_process=true` to automatically\n create a processing batch and submit it (zero-touch workflow).\n\n **Partial Success**: This endpoint uses partial success - valid objects are created\n even if some fail validation. Failed objects are returned separately with error details,\n allowing you to fix and retry only the failed ones.\n\n **Response**: Returns both succeeded and failed objects. The batch succeeds (200 OK) as long\n as at least one object is created. Check the `failed` array for objects that need attention.", "operationId": "create_objects_batch_v1_buckets__bucket_identifier__objects_batch_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "auto_process", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically create a batch and submit it for processing. When true, all successfully created objects will be immediately queued for processing without requiring separate batch calls. Ideal for onboarding and bulk upload workflows.", "default": false, "title": "Auto Process" }, "description": "Automatically create a batch and submit it for processing. When true, all successfully created objects will be immediately queued for processing without requiring separate batch calls. Ideal for onboarding and bulk upload workflows." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectsBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateObjectsBatchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects/{object_identifier}": { "get": { "tags": [ "Bucket Objects" ], "summary": "Get Object", "description": "This endpoint retrieves an object by its ID from the specified bucket.\n\n **Presigned URLs**: Set `return_presigned_urls=true` query parameter to generate fresh presigned download URLs\n for all blobs with S3 storage (default: false). URLs are added to each blob's properties as\n `presigned_url` and expire after 1 hour.\n\n **Document count**: `document_count` (how many documents this object produced, via vector-store\n lineage) is computed by default. It fans out to the vector partition, which on a cold/serverless\n partition can be slow \u2014 pass `include_document_count=false` to skip it for latency-sensitive,\n interactive views (e.g. an object-detail modal) that don't render the count. Even when requested,\n the count is best-effort and bounded by a deadline: it returns `null` rather than blocking the\n response if the partition is cold.", "operationId": "get_object_v1_buckets__bucket_identifier__objects__object_identifier__get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "object_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the object.", "title": "Object Identifier" }, "description": "The unique identifier of the object." }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage", "default": false, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage" }, { "name": "include_document_count", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Compute document_count via vector-store lineage (default true). Pass false to skip the vector fan-out for latency-sensitive views that don't render the count.", "default": true, "title": "Include Document Count" }, "description": "Compute document_count via vector-store lineage (default true). Pass false to skip the vector fan-out for latency-sensitive views that don't render the count." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "put": { "tags": [ "Bucket Objects" ], "summary": "Update Object", "description": "This endpoint updates an existing object in the specified bucket.\n The updated object must conform to the bucket's schema. It does not trigger processing.", "operationId": "update_object_v1_buckets__bucket_identifier__objects__object_identifier__put", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "object_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the object.", "title": "Object Identifier" }, "description": "The unique identifier of the object." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateObjectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Bucket Objects" ], "summary": "Partially Update Object", "description": "This endpoint partially updates an existing object in the specified bucket (PATCH operation).\n Only provided fields will be updated. At minimum, metadata can always be updated.\n Immutable fields like object_id and timestamps cannot be modified.\n It does not trigger processing.", "operationId": "patch_object_v1_buckets__bucket_identifier__objects__object_identifier__patch", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "object_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the object.", "title": "Object Identifier" }, "description": "The unique identifier of the object." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchObjectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Bucket Objects" ], "summary": "Delete Object", "description": "This endpoint deletes an object from the specified bucket.", "operationId": "delete_object_v1_buckets__bucket_identifier__objects__object_identifier__delete", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "object_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the object.", "title": "Object Identifier" }, "description": "The unique identifier of the object." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects/bulk-soft-delete": { "post": { "tags": [ "Bucket Objects" ], "summary": "Bulk Soft-Delete Objects", "description": "Soft-delete many objects by ID in one call (recoverable). Records are\n retained and flipped to a non-active lifecycle state (so retrieval excludes\n them), with the lifecycle propagated to downstream documents. Bucket stats\n are recomputed once. Designed for large purges (e.g. scoping a synced bucket\n to a subset) without the per-object webhook/stats storms of single delete.", "operationId": "bulk_soft_delete_objects_v1_buckets__bucket_identifier__objects_bulk_soft_delete_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSoftDeleteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSoftDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects/list": { "post": { "tags": [ "Bucket Objects" ], "summary": "List Objects", "description": "This endpoint lists objects in a bucket with cursor-based pagination, filtering, and sorting.\n\n **Filtering**: Use dot notation for metadata fields\n - Example: ?metadata.type=video&metadata.status=ready\n\n **Sorting**: Specify field and direction\n - Example: ?sort_field=metadata.created_at&sort_direction=desc\n - Direction: asc (ascending) or desc (descending), defaults to asc\n\n **Pagination**: Cursor-based for efficient deep pagination\n - First page: ?limit=100 (omit cursor)\n - Next pages: ?limit=100&cursor={next_cursor}\n - Use next_cursor from response to navigate\n - No limit on pagination depth\n\n **Total Count**: Optional (expensive operation)\n - Use ?include_total=true to get total count\n - Adds 50-200ms to response time\n - Returns total, page, page_size, total_pages fields in pagination response", "operationId": "list_objects_v1_buckets__bucket_identifier__objects_list_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListObjectsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListObjectsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/objects/aggregate": { "post": { "tags": [ "Bucket Objects" ], "summary": "Aggregate Objects", "description": "This endpoint performs aggregation operations on objects in a bucket.\n\n **Aggregation Framework**: Provides MongoDB-style aggregation operations:\n - GROUP BY: Group objects by one or more fields\n - Aggregations: COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT, etc.\n - Date Operations: Truncate or extract date parts for time-series analysis\n - Filtering: Pre-aggregation filters (WHERE) and post-aggregation filters (HAVING)\n - Sorting & Limiting: Control result ordering and size\n\n **Use Cases**:\n - Count objects by status or category\n - Calculate daily/monthly upload statistics\n - Analyze content distribution and trends\n - Generate reports with multiple metrics\n\n **Note**: This endpoint works with both MongoDB objects and Qdrant documents\n using the same interface. The system automatically selects the appropriate\n aggregation provider.", "operationId": "aggregate_objects_v1_buckets__bucket_identifier__objects_aggregate_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectAggregationRequest", "description": "Aggregation configuration specifying grouping, metrics, and filters." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectAggregationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches": { "post": { "tags": [ "Bucket Batches" ], "summary": "Create Batch", "description": "Create a new batch for grouping bucket objects.", "operationId": "create_batch_v1_buckets__bucket_identifier__batches_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "skip_validation", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip object existence validation. Use this for large batches (>10k objects) or when you're certain all object IDs are valid. Improves performance significantly.", "default": false, "title": "Skip Validation" }, "description": "Skip object existence validation. Use this for large batches (>10k objects) or when you're certain all object IDs are valid. Improves performance significantly." }, { "name": "auto_submit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Submit the batch for processing immediately after creation. When false (default) the batch is returned in DRAFT status and the caller must POST /submit separately. Symmetric with the auto_process flag on POST /buckets/{id}/objects, and explicit by design \u2014 earlier the only way to auto-submit was via the object endpoint, which made batch lifecycle behaviour non-obvious for callers driving the batch endpoint directly. Accepted here (query) or in the JSON body as {\"auto_submit\": true}; the query parameter wins when both are supplied.", "title": "Auto Submit" }, "description": "Submit the batch for processing immediately after creation. When false (default) the batch is returned in DRAFT status and the caller must POST /submit separately. Symmetric with the auto_process flag on POST /buckets/{id}/objects, and explicit by design \u2014 earlier the only way to auto-submit was via the object endpoint, which made batch lifecycle behaviour non-obvious for callers driving the batch endpoint directly. Accepted here (query) or in the JSON body as {\"auto_submit\": true}; the query parameter wins when both are supplied." }, { "name": "trigger_processing", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Deprecated alias of auto_submit (kept for callers taught by older docs/hints). Accepted in query or JSON body; auto_submit wins when both are supplied.", "title": "Trigger Processing" }, "description": "Deprecated alias of auto_submit (kept for callers taught by older docs/hints). Accepted in query or JSON body; auto_submit wins when both are supplied." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/objects": { "post": { "tags": [ "Bucket Batches" ], "summary": "Add Objects to Batch", "description": "Add objects to an existing batch. The batch must be in 'draft' status.", "operationId": "add_objects_to_batch_v1_buckets__bucket_identifier__batches__batch_id__objects_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "skip_validation", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip object existence validation. Use this for large batches (>10k objects) or when you're certain all object IDs are valid. Improves performance significantly.", "default": false, "title": "Skip Validation" }, "description": "Skip object existence validation. Use this for large batches (>10k objects) or when you're certain all object IDs are valid. Improves performance significantly." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddObjectsToBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/estimate-cost": { "post": { "tags": [ "Bucket Batches" ], "summary": "Estimate Batch Cost (pre-flight, dry-run)", "description": "Pre-flight estimate of the credits a DRAFT batch will consume on submit, plus how many of its objects were already extracted \u2014 so a force/replace re-run that re-pays GPU extraction surfaces its cost BEFORE submitting. Does not consume credits or change the batch's contents/status; it DOES refresh a DRAFT batch's activity timestamp so the draft-TTL reaper grants a fresh grace window while you confirm the cost.", "operationId": "estimate_batch_cost_endpoint_v1_buckets__bucket_identifier__batches__batch_id__estimate_cost_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCostEstimate" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/submit": { "post": { "tags": [ "Bucket Batches" ], "summary": "Submit Batch for Processing", "description": "Submit a draft batch for asynchronous processing. The batch must be in 'DRAFT' status and contain objects.", "operationId": "submit_batch_v1_buckets__bucket_identifier__batches__batch_id__submit_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Bypass the concurrent batch dedup check. Use when you intentionally want to reprocess the same bucket+collection combination while another batch is in flight.", "default": false, "title": "Force" }, "description": "Bypass the concurrent batch dedup check. Use when you intentionally want to reprocess the same bucket+collection combination while another batch is in flight." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/submit-all": { "post": { "tags": [ "Bucket Batches" ], "summary": "Submit All Draft Batches", "description": "Submit all DRAFT batches in this bucket for processing in a single request. Bypasses per-request rate limiting. Each batch is submitted sequentially and subject to the same admission control as individual submit.", "operationId": "submit_all_drafts_v1_buckets__bucket_identifier__batches_submit_all_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Submit All Drafts V1 Buckets Bucket Identifier Batches Submit All Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/bulk-submit": { "post": { "tags": [ "Bucket Batches" ], "summary": "Bulk-submit a whole bucket as N auto-chunked, auto-queued batches", "description": "One call that streams the bucket's objects (paginated, de-duplicated), chunks them server-side into `chunk_size`-object batches, and submits each (accept-and-queue). Replaces the client-side chunk loop + cursor pacing \u2014 no 409 cursor-overlap, no 5k count-timeout, no manual 429 handling. Poll the returned batch ids / `batch_group_id` for QUEUED -> PROCESSING.", "operationId": "bulk_submit_batches_v1_buckets__bucket_identifier__batches_bulk_submit_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The bucket to ingest.", "title": "Bucket Identifier" }, "description": "The bucket to ingest." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubmitBatchesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubmitBatchesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/list": { "post": { "tags": [ "Bucket Batches" ], "summary": "List Batches", "description": "List batches with pagination and filtering options.", "operationId": "list_batches_v1_buckets__bucket_identifier__batches_list_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBatchesRequest", "default": { "offset": 0, "limit": 100 } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBatchesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}": { "get": { "tags": [ "Bucket Batches" ], "summary": "Get Batch Configuration", "description": "Retrieve batch configuration and historical data from MongoDB. Status is automatically synchronized from Task API. For real-time monitoring, use GET /v1/tasks/{task_id} (Redis, faster).", "operationId": "get_batch_v1_buckets__bucket_identifier__batches__batch_id__get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Bucket Batches" ], "summary": "Delete Batch", "description": "Delete a batch by its ID.", "operationId": "delete_batch_v1_buckets__bucket_identifier__batches__batch_id__delete", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Bucket Batches" ], "summary": "Partially Update Batch", "description": "This endpoint partially updates a batch (PATCH operation).\n Only provided fields will be updated. At minimum, metadata can always be updated.\n Immutable fields like batch_id and timestamps cannot be modified.", "operationId": "patch_batch_v1_buckets__bucket_identifier__batches__batch_id__patch", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/audit": { "get": { "tags": [ "Bucket Batches" ], "summary": "Tier-completion invariant audit", "description": "Returns the per-tier completion accounting for a batch: how many objects were submitted, how many ended up in the per-object success ledger (processed_objects), how many in the per-object failure ledger (failed_documents), how many were skipped, and how many are 'lost' (submitted but absent from both per-object ledgers).\n\nPhase 1 of INGESTION_RELIABILITY_PLAN.md. ``has_lost_objects=true`` is a smoking gun for the row-failure-swallow class of bug \u2014 the tier was marked COMPLETED but rows silently went missing. Compare against ``tier_tasks[].audit`` (persisted at completion) to see the snapshot at the time the callback fired.", "operationId": "get_batch_audit_v1_buckets__bucket_identifier__batches__batch_id__audit_get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/documents": { "delete": { "tags": [ "Bucket Batches" ], "summary": "Delete Documents Produced by Batch", "description": "Delete all documents that were produced by this batch. Useful for cleaning up documents from batches that produced bad data (e.g. null vectors). Only works for terminal batches.", "operationId": "delete_batch_documents_v1_buckets__bucket_identifier__batches__batch_id__documents_delete", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Batch Documents V1 Buckets Bucket Identifier Batches Batch Id Documents Delete" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/cancel": { "post": { "tags": [ "Bucket Batches" ], "summary": "Cancel Batch", "description": "Cancel a submitted/processing batch: cancels Ray job via engine and marks task/batch as CANCELLED.", "operationId": "cancel_batch_v1_buckets__bucket_identifier__batches__batch_id__cancel_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732).", "title": "Reason" }, "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/cancel": { "post": { "tags": [ "Bucket Batches" ], "summary": "Cancel Tier", "description": "Cancel a single tier within a batch without affecting other tiers. Cancels all Ray and Celery jobs for this tier and marks it CANCELED.", "operationId": "cancel_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__cancel_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "Zero-based tier number to cancel.", "title": "Tier Num" }, "description": "Zero-based tier number to cancel." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732).", "title": "Reason" }, "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Tier V1 Buckets Bucket Identifier Batches Batch Id Tiers Tier Num Cancel Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/jobs/{ray_job_id}/cancel": { "post": { "tags": [ "Bucket Batches" ], "summary": "Cancel Job", "description": "Cancel a single Ray job within a tier without affecting sibling jobs.", "operationId": "cancel_job_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__jobs__ray_job_id__cancel_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "Zero-based tier number.", "title": "Tier Num" }, "description": "Zero-based tier number." }, { "name": "ray_job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Ray job ID to cancel.", "title": "Ray Job Id" }, "description": "Ray job ID to cancel." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732).", "title": "Reason" }, "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Job V1 Buckets Bucket Identifier Batches Batch Id Tiers Tier Num Jobs Ray Job Id Cancel Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/retry": { "post": { "tags": [ "Bucket Batches" ], "summary": "Retry Tier with Resource Overrides", "description": "Retry a failed or canceled tier, optionally with modified resource parameters. Useful for retrying OOM failures with more memory.", "operationId": "retry_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__retry_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "Zero-based tier number to retry.", "title": "Tier Num" }, "description": "Zero-based tier number to retry." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Resource overrides: {requires_gpu, priority}.", "examples": [ { "requires_gpu": true, "priority": 50 } ], "title": "Resource Overrides" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Retry Tier V1 Buckets Bucket Identifier Batches Batch Id Tiers Tier Num Retry Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/heal": { "post": { "tags": [ "Bucket Batches" ], "summary": "Manual Self-Healing", "description": "Trigger a self-healing action on a tier: kill duplicate jobs, detect stuck jobs, sync extractor status, or check the circuit breaker.", "operationId": "heal_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__heal_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "Zero-based tier number.", "title": "Tier Num" }, "description": "Zero-based tier number." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_heal_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__heal_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Heal Tier V1 Buckets Bucket Identifier Batches Batch Id Tiers Tier Num Heal Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/diagnose": { "get": { "tags": [ "Bucket Batches" ], "summary": "Diagnose Batch", "description": "Aggregate diagnostic information for a batch: status, timing, errors, infrastructure events, progress, failed documents, and recommendations.", "operationId": "diagnose_batch_v1_buckets__bucket_identifier__batches__batch_id__diagnose_get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Diagnose Batch V1 Buckets Bucket Identifier Batches Batch Id Diagnose Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/failed-documents": { "get": { "tags": [ "Bucket Batches" ], "summary": "Get Failed Documents for Batch", "description": "Retrieve failed documents for a batch, optionally filtered by tier or collection.", "operationId": "get_failed_documents_v1_buckets__bucket_identifier__batches__batch_id__failed_documents_get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tier Num" } }, { "name": "collection_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Failed Documents V1 Buckets Bucket Identifier Batches Batch Id Failed Documents Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/retry": { "post": { "tags": [ "Bucket Batches" ], "summary": "Retry Failed Documents", "description": "Retry failed documents in a batch with intelligent filtering by error type and tier.", "operationId": "retry_batch_v1_buckets__bucket_identifier__batches__batch_id__retry_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryBatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Retry Batch V1 Buckets Bucket Identifier Batches Batch Id Retry Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/resubmit": { "post": { "tags": [ "Bucket Batches" ], "summary": "Resubmit Failed Batch", "description": "Re-run a terminal (FAILED/CANCELED/COMPLETED/\u2026) batch: resets it to DRAFT and auto-submits by default, so the verb matches the behavior. Pass auto_submit=false to only park it as DRAFT \u2014 it must then be submitted manually before the draft TTL expires.", "operationId": "resubmit_batch_v1_buckets__bucket_identifier__batches__batch_id__resubmit_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "from_tier", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Resubmit starting from this tier number (0-indexed). Tiers before from_tier are preserved as COMPLETED. Omit to resubmit all tiers from scratch.", "title": "From Tier" }, "description": "Resubmit starting from this tier number (0-indexed). Tiers before from_tier are preserved as COMPLETED. Omit to resubmit all tiers from scratch." }, { "name": "auto_submit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Auto-submit after the DRAFT reset. DEFAULT TRUE \u2014 'resubmit' means re-run the batch, so one call does both. Pass false to only reset to DRAFT (parked; you must POST /submit before the draft TTL expires or the zombie reaper cancels it). Accepted here (query) or in the JSON body as {\"auto_submit\": false}.", "title": "Auto Submit" }, "description": "Auto-submit after the DRAFT reset. DEFAULT TRUE \u2014 'resubmit' means re-run the batch, so one call does both. Pass false to only reset to DRAFT (parked; you must POST /submit before the draft TTL expires or the zombie reaper cancels it). Accepted here (query) or in the JSON body as {\"auto_submit\": false}." }, { "name": "trigger_processing", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Deprecated alias of auto_submit (kept for callers taught by the old submit-endpoint 400 hint). Accepted in query or JSON body; auto_submit wins when both are supplied.", "title": "Trigger Processing" }, "description": "Deprecated alias of auto_submit (kept for callers taught by the old submit-endpoint 400 hint). Accepted in query or JSON body; auto_submit wins when both are supplied." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Optional body; {\"auto_submit\": bool} (or the deprecated {\"trigger_processing\": bool}) is honored.", "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Resubmit Batch V1 Buckets Bucket Identifier Batches Batch Id Resubmit Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/retry-vector-write": { "post": { "tags": [ "Bucket Batches" ], "summary": "Retry Vector Write from S3", "description": "Retry vector write by reading processed output from S3. Use when validation detects 'vector_write_failed'.", "operationId": "retry_qdrant_write_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__retry_vector_write_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "path", "required": true, "schema": { "type": "integer", "description": "The tier number to retry (0-based).", "title": "Tier Num" }, "description": "The tier number to retry (0-based)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Retry Qdrant Write V1 Buckets Bucket Identifier Batches Batch Id Tiers Tier Num Retry Vector Write Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/batches/{batch_id}/logs": { "get": { "tags": [ "Bucket Batches" ], "summary": "Get Ray Job Logs for Batch", "description": "Retrieve Ray job submission logs for a batch's processing tiers. You can get logs for a specific tier or all tiers. User must have access to the batch to retrieve logs.", "operationId": "get_batch_logs_v1_buckets__bucket_identifier__batches__batch_id__logs_get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket.", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket." }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "tier_num", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional tier number (0-based). If not provided, returns logs for all tiers.", "title": "Tier Num" }, "description": "Optional tier number (0-based). If not provided, returns logs for all tiers." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/batches/list": { "post": { "tags": [ "Batches" ], "summary": "List All Batches", "description": "List batches across all buckets in the organization. Filter with `status`, `bucket_id`, `collection_id`, or `namespace_id` in the request body. NOTE: the X-Namespace header does NOT narrow this endpoint \u2014 it is organization-scoped by design. Pass `namespace_id` in the body instead.", "operationId": "list_all_batches_v1_batches_list_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBatchesRequest", "default": { "offset": 0, "limit": 100 } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBatchesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/batches/queue": { "get": { "tags": [ "Batches" ], "summary": "Batch Queue Status", "description": "View the Ray job queue: active jobs, max concurrency, and waiting batches with priorities.", "operationId": "get_queue_status_v1_batches_queue_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Queue Status V1 Batches Queue Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/batches/{batch_id}/cancel": { "post": { "tags": [ "Batches" ], "summary": "Cancel Batch", "description": "Cancel a submitted/processing batch by ID without requiring the bucket_id. Cancels all associated Ray and Celery jobs, releases queue slots, and marks the batch as CANCELLED.", "operationId": "cancel_batch_by_id_v1_batches__batch_id__cancel_post", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732).", "title": "Reason" }, "description": "Optional human reason for the cancel, recorded on the batch record for audit (BACKE-2732)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/batches/{batch_id}": { "get": { "tags": [ "Batches" ], "summary": "Get Batch by ID", "description": "Retrieve a single batch by its ID without requiring the bucket_id. Returns full batch details including real-time progress (objects_processed, total_objects, items_per_second, eta_seconds) for in-flight batches.", "operationId": "get_batch_by_id_v1_batches__batch_id__get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the batch.", "title": "Batch Id" }, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads": { "post": { "tags": [ "Bucket Uploads" ], "summary": "Create Upload", "description": "Generate a presigned URL for direct S3 upload.\n\n This endpoint validates all requirements BEFORE generating the presigned URL,\n ensuring immediate feedback if something is wrong (bucket inactive, quota exceeded, etc.).\n\n **Duplicate Detection (Enabled by Default)**:\n - If `file_hash` provided and `skip_duplicates=true`: Checks for existing upload\n - If duplicate found: Returns existing upload (200 OK) with `is_duplicate=true`\n - If new file: Returns presigned URL (201 Created) with `is_duplicate=false`\n\n **Two-Step Flow**:\n 1. Call this endpoint \u2192 Get presigned URL\n 2. PUT file to presigned URL \u2192 Upload directly to S3\n 3. Call confirm endpoint \u2192 Verify upload and create object", "operationId": "create_upload_v1_buckets__bucket_identifier__uploads_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads/{upload_id}": { "get": { "tags": [ "Bucket Uploads" ], "summary": "Get Upload", "description": "Retrieve an upload by its ID.\n\n Use this to check upload status, get S3 key, or retrieve created object_id after confirmation.\n\n **Presigned URLs**: Set `return_presigned_urls=true` query parameter to generate fresh presigned download URLs (default: false).\n The presigned URLs expire after 1 hour and allow direct download from S3.", "operationId": "get_upload_v1_buckets__bucket_identifier__uploads__upload_id__get", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" }, { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the upload", "title": "Upload Id" }, "description": "The unique identifier of the upload" }, { "name": "return_presigned_urls", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Generate fresh presigned download URLs for all blobs with S3 storage", "default": false, "title": "Return Presigned Urls" }, "description": "Generate fresh presigned download URLs for all blobs with S3 storage" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Bucket Uploads" ], "summary": "Delete Upload", "description": "Cancel an upload and optionally delete the S3 object.\n\n Cannot cancel uploads with status COMPLETED.\n Can cancel uploads with status: PENDING, IN_PROGRESS, FAILED.", "operationId": "delete_upload_v1_buckets__bucket_identifier__uploads__upload_id__delete", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" }, { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the upload", "title": "Upload Id" }, "description": "The unique identifier of the upload" }, { "name": "delete_s3_object", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to delete the S3 object", "default": true, "title": "Delete S3 Object" }, "description": "Whether to delete the S3 object" } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads/list": { "post": { "tags": [ "Bucket Uploads" ], "summary": "List Uploads", "description": "List uploads in a bucket with filtering, sorting, search, and pagination.\n\n **Filtering**: Use LogicalOperator with shorthand syntax\n - Simple: `{\"status\": \"PENDING\", \"metadata.campaign\": \"summer_2024\"}`\n - Complex: `{\"AND\": [{\"field\": \"file_size_bytes\", \"operator\": \"gte\", \"value\": 1000000}]}`\n\n **Sorting**: Specify field and direction\n - Example: `{\"field\": \"created_at\", \"direction\": \"desc\"}`\n\n **Search**: Full-text search across filename and metadata\n - Example: `\"search\": \"video\"`\n\n **Pagination**: Use limit and offset\n - Example: `\"limit\": 50, \"offset\": 100`", "operationId": "list_uploads_v1_buckets__bucket_identifier__uploads_list_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUploadsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads/{upload_id}/confirm": { "post": { "tags": [ "Bucket Uploads" ], "summary": "Confirm Upload", "description": "Verify S3 upload completion and create bucket object.\n\n After uploading to S3 using the presigned URL, call this endpoint to:\n 1. Verify the file exists in S3\n 2. Validate ETag and file size (if provided)\n 3. Create bucket object (default, unless create_object_on_confirm=false)\n 4. Update upload status to COMPLETED\n\n **Sync vs Async**:\n - Files < 100MB: Processed synchronously (~100ms)\n - Files >= 100MB or async=true: Processed asynchronously (returns task_id)\n\n **Duplicate Detection**:\n - If file hash matches existing upload, marks as duplicate\n - References original object_id if available", "operationId": "confirm_upload_v1_buckets__bucket_identifier__uploads__upload_id__confirm_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" }, { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the upload", "title": "Upload Id" }, "description": "The unique identifier of the upload" }, { "name": "async", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Process confirmation asynchronously (recommended for files >= 100MB)", "default": false, "title": "Async" }, "description": "Process confirmation asynchronously (recommended for files >= 100MB)" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmUploadRequest" }, { "type": "null" } ], "title": "Confirm Request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads/batch": { "post": { "tags": [ "Bucket Uploads" ], "summary": "Batch Create Uploads", "description": "Generate multiple presigned URLs in a single request.\n\n All uploads belong to the same bucket (from path parameter).\n Maximum 100 uploads per batch.\n\n Shared metadata is merged with individual upload metadata (individual takes precedence).", "operationId": "create_uploads_batch_v1_buckets__bucket_identifier__uploads_batch_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUploadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/buckets/{bucket_identifier}/uploads/confirm/batch": { "post": { "tags": [ "Bucket Uploads" ], "summary": "Batch Confirm Uploads", "description": "Confirm multiple uploads in a single request (processed asynchronously).\n\n Maximum 100 confirmations per batch.\n All uploads must belong to the same bucket.\n\n Returns a task_id to track progress via GET /v1/tasks/{task_id}.", "operationId": "confirm_uploads_batch_v1_buckets__bucket_identifier__uploads_confirm_batch_post", "parameters": [ { "name": "bucket_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the bucket", "title": "Bucket Identifier" }, "description": "The unique identifier of the bucket" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchConfirmRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchConfirmResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/tasks/{task_id}": { "delete": { "tags": [ "Tasks" ], "summary": "Kill Task", "description": "Kill a task (idempotent - succeeds even if task doesn't exist or is already killed).", "operationId": "kill_task_v1_tasks__task_id__delete", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Tasks" ], "summary": "Get Task Information", "description": "Retrieve a task by its ID.\n\n A task may have an expiration time, after which it will still be returned but marked as expired.\n This allows tracking of historical tasks while indicating their current validity state.", "operationId": "get_task_v1_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/tasks/list": { "post": { "tags": [ "Tasks" ], "summary": "List Tasks", "description": "List tasks with optional filtering, sorting, and pagination.\n\n **Filter Options**:\n - `status`: Filter by specific status (PENDING, IN_PROGRESS, COMPLETED, FAILED, etc.)\n - `task_type`: Filter by task type\n\n **Examples**:\n - All tasks: `{}`\n - Failed tasks only: `{\"status\": \"FAILED\"}`\n - Pending batches: `{\"status\": \"PENDING\", \"task_type\": \"API_BUCKETS_UPLOADS_BATCH_CONFIRM\"}`\n - In-progress tasks: `{\"status\": \"IN_PROGRESS\"}`", "operationId": "list_tasks_v1_tasks_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTasksRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTasksResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Create a new webhook for the user's organization.", "operationId": "create_webhook_v1_organizations_webhooks_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook-Input" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook-Output" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/webhooks/list": { "post": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all webhooks for the user's organization.", "operationId": "list_webhooks_v1_organizations_webhooks_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/webhooks/{identifier}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook", "description": "Get a single webhook by its ID.", "operationId": "get_webhook_v1_organizations_webhooks__identifier__get", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook-Output" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update Webhook", "description": "Update an existing webhook.", "operationId": "update_webhook_v1_organizations_webhooks__identifier__put", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook-Input" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook-Output" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Delete a webhook (idempotent - succeeds even if already deleted).", "operationId": "delete_webhook_v1_organizations_webhooks__identifier__delete", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Identifier" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/list": { "post": { "tags": [ "Notifications" ], "summary": "List Notifications", "description": "List all notifications for the user's organization.", "operationId": "list_notifications_v1_notifications_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNotificationsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNotificationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/read/all": { "post": { "tags": [ "Notifications" ], "summary": "Mark All As Read", "description": "Mark all notifications as read for a user.", "operationId": "mark_all_as_read_v1_notifications_read_all_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAsReadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/preferences": { "get": { "tags": [ "Notifications" ], "summary": "Get Preferences", "description": "Get notification preferences for the organization.", "operationId": "get_preferences_v1_notifications_preferences_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Preferences V1 Notifications Preferences Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "tags": [ "Notifications" ], "summary": "Update Preferences", "description": "Update notification preferences for the organization.", "operationId": "update_preferences_v1_notifications_preferences_put", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePreferencesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Preferences V1 Notifications Preferences Put" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/unread/count": { "get": { "tags": [ "Notifications" ], "summary": "Get Unread Count", "description": "Get count of unread notifications.", "operationId": "get_unread_count_v1_notifications_unread_count_get", "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Unread Count V1 Notifications Unread Count Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/{notification_id}": { "get": { "tags": [ "Notifications" ], "summary": "Get Notification", "description": "Get a single notification by its ID.", "operationId": "get_notification_v1_notifications__notification_id__get", "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Notification Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Notifications" ], "summary": "Delete Notification", "description": "Delete a notification (idempotent - succeeds even if already deleted).", "operationId": "delete_notification_v1_notifications__notification_id__delete", "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Notification Id" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/{notification_id}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark As Read", "description": "Mark a notification as read.", "operationId": "mark_as_read_v1_notifications__notification_id__read_post", "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Notification Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/preferences/reminders": { "get": { "tags": [ "Notifications" ], "summary": "Get Reminder Preferences", "description": "Get reminder/nudge email preferences for the organization.\n\nThese preferences control funnel-based onboarding nudges,\nre-engagement emails, and feature tips.", "operationId": "get_reminder_preferences_v1_notifications_preferences_reminders_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderPreferencesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "tags": [ "Notifications" ], "summary": "Update Reminder Preferences", "description": "Update reminder/nudge email preferences for the organization.\n\nYou can update individual preferences without affecting others:\n- enabled: Master toggle for all reminder emails\n- onboarding_nudges: Funnel progression nudges\n- engagement_reminders: Re-engagement emails for inactivity\n- feature_tips: Helpful tips and inspiration\n- quiet_hours_start/end: Hours (0-23 UTC) when no emails are sent", "operationId": "update_reminder_preferences_v1_notifications_preferences_reminders_put", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReminderPreferencesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderPreferencesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/emails/recent": { "get": { "tags": [ "Notifications" ], "summary": "Get Recent Email Sends", "description": "Get recent emails sent via Resend with delivery status.\n\nReturns a list of sent emails enriched with Resend delivery events\n(delivered, bounced, complained, etc.) for visibility into the email pipeline.", "operationId": "get_recent_email_sends_v1_notifications_emails_recent_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Recent Email Sends V1 Notifications Emails Recent Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/funnel/state": { "get": { "tags": [ "Notifications" ], "summary": "Get Funnel State", "description": "Get the current funnel state for the organization.\n\nReturns the user's position in the onboarding funnel, including:\n- Current stage\n- When each stage was reached\n- Nudges that have been sent\n- Last activity timestamp", "operationId": "get_funnel_state_v1_notifications_funnel_state_get", "parameters": [], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Funnel State V1 Notifications Funnel State Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/notifications/funnel/advance": { "post": { "tags": [ "Notifications" ], "summary": "Advance Funnel Stage", "description": "Advance the funnel stage from the client side.\n\nStudio calls this when key milestones happen in-browser that the server\ncannot observe directly (e.g. first_search executed in the test tab).\nAccepts both resource-creation stages and activation funnel stages.", "operationId": "advance_funnel_stage_v1_notifications_funnel_advance_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_advance_funnel_stage_v1_notifications_funnel_advance_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Advance Funnel Stage V1 Notifications Funnel Advance Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/tickets": { "post": { "tags": [ "Support" ], "summary": "Create Support Ticket", "operationId": "create_ticket_v1_support_tickets_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Support" ], "summary": "List Support Tickets", "operationId": "list_tickets_v1_support_tickets_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/tickets/list": { "post": { "tags": [ "Support" ], "summary": "List Support Tickets (org + global).", "operationId": "list_tickets_v1_support_tickets_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/tickets/{ticket_identifier}": { "get": { "tags": [ "Support" ], "summary": "Get Support Ticket (with message thread).", "operationId": "get_ticket_v1_support_tickets__ticket_identifier__get", "parameters": [ { "name": "ticket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Support" ], "summary": "Update a support ticket (status/priority).", "operationId": "update_ticket_v1_support_tickets__ticket_identifier__patch", "parameters": [ { "name": "ticket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTicketRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/tickets/{ticket_identifier}/messages": { "post": { "tags": [ "Support" ], "summary": "Reply to a support ticket.", "operationId": "add_ticket_message_v1_support_tickets__ticket_identifier__messages_post", "parameters": [ { "name": "ticket_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/comms/list": { "post": { "tags": [ "Support" ], "summary": "List correspondence (ticket messages + broadcasts, org + global).", "operationId": "list_comms_v1_support_comms_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/comms": { "get": { "tags": [ "Support" ], "summary": "List Correspondence", "operationId": "list_comms_v1_support_comms_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/comms/broadcast": { "post": { "tags": [ "Support" ], "summary": "Create a broadcast communication (Mixpeek admin only).", "operationId": "create_broadcast_v1_support_comms_broadcast_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/videos/upload-url": { "post": { "tags": [ "Support" ], "summary": "Presigned PUT to upload a support video to cold storage (admin only).", "operationId": "create_video_upload_url_v1_support_videos_upload_url_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoUploadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoUploadUrlResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/videos": { "post": { "tags": [ "Support" ], "summary": "Register a support video (admin only); triggers Gemini review for uploads.", "operationId": "create_video_v1_support_videos_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Support" ], "summary": "List Support Videos", "operationId": "list_videos_v1_support_videos_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideosRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideosResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/videos/list": { "post": { "tags": [ "Support" ], "summary": "List curated support videos (org + global).", "operationId": "list_videos_v1_support_videos_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideosRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVideosResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/support/videos/{video_identifier}": { "get": { "tags": [ "Support" ], "summary": "Get a support video (with presigned playback URL + chapters).", "operationId": "get_video_v1_support_videos__video_identifier__get", "parameters": [ { "name": "video_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Video Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/taxonomies": { "post": { "tags": [ "Taxonomies" ], "summary": "Create Taxonomy", "description": "Create a taxonomy and return the created resource.", "operationId": "create_taxonomy_v1_taxonomies_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxonomyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Taxonomies" ], "summary": "List taxonomies (GET alias for POST /list).", "description": "List taxonomies with optional filters and pagination.", "operationId": "list_taxonomies_v1_taxonomies_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTaxonomiesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTaxonomiesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_identifier}": { "get": { "tags": [ "Taxonomies" ], "summary": "Get Taxonomy", "description": "Get a taxonomy by ID or name.", "operationId": "get_taxonomy_v1_taxonomies__taxonomy_identifier__get", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name" }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional taxonomy version to fetch", "title": "Version" }, "description": "Optional taxonomy version to fetch" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Taxonomies" ], "summary": "Delete Taxonomy", "description": "This endpoint deletes a taxonomy and all its resources including:\n - Taxonomy versions (version snapshots)\n - Taxonomy metadata from MongoDB\n\n The deletion is performed synchronously and returns when complete.", "operationId": "delete_taxonomy_v1_taxonomies__taxonomy_identifier__delete", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Taxonomies" ], "summary": "Partially Update Taxonomy", "description": "Update a taxonomy's metadata.\n\n **Metadata Only Updates:**\n This endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable\n to ensure consistency for join history and dependent resources.\n\n **Fields You CAN Update:**\n - taxonomy_name: Rename the taxonomy\n - description: Update documentation\n - metadata: Update custom metadata\n\n **Fields You CANNOT Update:**\n - config: Taxonomy configuration (retriever_id, input_mappings, collections)\n - taxonomy_type: Type (flat vs hierarchical)\n\n **Need to Modify Core Logic?**\n Use POST /{taxonomy_identifier}/clone instead to modify configuration,\n retriever_id, input_mappings, or collections.", "operationId": "patch_taxonomy_v1_taxonomies__taxonomy_identifier__patch", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchTaxonomyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/versions": { "post": { "tags": [ "Taxonomies" ], "summary": "Create Taxonomy Version", "description": "Create a new version for a taxonomy with a new config snapshot.", "operationId": "create_taxonomy_version_v1_taxonomies__taxonomy_id__versions_post", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID (tax_...)", "title": "Taxonomy Id" }, "description": "Taxonomy ID (tax_...)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Taxonomies" ], "summary": "List Taxonomy Versions", "description": "List all versions for a taxonomy (head included as latest).", "operationId": "list_taxonomy_versions_v1_taxonomies__taxonomy_id__versions_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID (tax_...)", "title": "Taxonomy Id" }, "description": "Taxonomy ID (tax_...)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTaxonomiesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_identifier}/clone": { "post": { "tags": [ "Taxonomies" ], "summary": "Clone Taxonomy", "description": "Clone a taxonomy with optional modifications.\n\n **Purpose:**\n Creates a NEW taxonomy (with new ID) based on an existing one. This is the\n recommended way to iterate on taxonomy designs when you need to modify core\n logic that PATCH doesn't allow (config, retriever_id, input_mappings).\n\n **Clone vs PATCH vs Template:**\n - **PATCH**: Update metadata only (name, description, metadata)\n - **Clone**: Copy and modify core logic (config, retriever, collections)\n - **Template**: Start from a pre-configured pattern (for new projects)\n\n **Common Use Cases:**\n - Fix configuration errors without losing join history\n - Change retriever or input mappings\n - Modify enrichment fields or collection configuration\n - Test modifications before replacing production taxonomy\n - Create variants for different datasets\n\n **How it works:**\n 1. Source taxonomy is copied\n 2. You provide a new name (REQUIRED)\n 3. Optionally override any other fields (description, config)\n 4. A new taxonomy is created with a new ID\n 5. Original taxonomy remains unchanged", "operationId": "clone_taxonomy_v1_taxonomies__taxonomy_identifier__clone_post", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Source taxonomy ID or name to clone.", "title": "Taxonomy Identifier" }, "description": "Source taxonomy ID or name to clone." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneTaxonomyRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneTaxonomyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/from-documents": { "post": { "tags": [ "Taxonomies" ], "summary": "Create a taxonomy from a document selection (one gesture)", "description": "Promote a document selection (e.g. a lasso/cluster selection in the cluster\nvisualization) into a NEW flat taxonomy in one call.\n\nCreates, in order:\n1. a **node collection** mirroring the selection's vector index (same vector\n name, dimensions, and feature_uri \u2014 no re-embedding, no GPU work),\n2. a **vector-search retriever** over it,\n3. the **flat taxonomy** wired to both (input_mappings map an incoming\n document's stored embedding onto the retriever),\n4. the **first node**: a document whose anchor vector is the centroid of the\n referenced documents' stored vectors, labeled `node_label`.\n\nDocuments enriched through the taxonomy afterwards are labeled with the\nnearest node's `label`. To add more nodes later, use\n`POST /v1/taxonomies/{taxonomy_id}/nodes/from-documents`.\n\nResources created before a failing step are cleaned up best-effort.", "operationId": "create_taxonomy_from_documents_v1_taxonomies_from_documents_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxonomyFromDocumentsRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyNodeFromDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_identifier}/nodes/from-documents": { "post": { "tags": [ "Taxonomies" ], "summary": "Add a taxonomy node derived from a document selection", "description": "Add a node to an existing **flat** taxonomy from a document selection.\n\nThe node is an ordinary document in the taxonomy's node (source) collection:\nits anchor vector is the **centroid of the referenced documents' stored\nvectors** and its `label` is `node_label`. Future documents enriched through\nthis taxonomy are labeled with the nearest node's `label`.\n\nOnly stored vectors are read \u2014 no re-embedding or GPU work. Documents that\ncan't contribute (missing, no matching vector) are skipped and reported in\n`documents_skipped`; the call fails only when NO document contributes.\n\nHierarchical taxonomies are not supported here (their nodes are whole\ncollections) \u2014 the error points you to the flat-taxonomy path.", "operationId": "create_taxonomy_node_from_documents_v1_taxonomies__taxonomy_identifier__nodes_from_documents_post", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNodeFromDocumentsRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyNodeFromDocumentsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/list": { "post": { "tags": [ "Taxonomies" ], "summary": "List Taxonomies", "description": "List taxonomies with optional filters and pagination.", "operationId": "list_taxonomies_v1_taxonomies_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTaxonomiesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTaxonomiesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/execute/{taxonomy_identifier}": { "post": { "tags": [ "Taxonomies" ], "summary": "Test taxonomy configuration (validation only) \u2014 DEPRECATED path", "description": "\u26a0\ufe0f VALIDATION ENDPOINT ONLY - Not for production enrichment!\n\nDEPRECATED path shape \u2014 prefer POST /taxonomies/{id}/execute (id-first,\nconsistent with retrievers). This verb-first path still works.\n\nThis endpoint validates taxonomy configuration with 1-5 sample documents.\nResults are returned immediately and NOT persisted to any collection.\n\n\u274c DO NOT USE FOR:\n- Enriching entire collections (use taxonomy_applications instead)\n- Batch processing documents (automatic during ingestion)\n- Persisting enriched documents (use retriever pipelines instead)\n\n\u2705 USE THIS FOR:\n- Testing taxonomy configuration is correct\n- Validating retriever finds matching taxonomy nodes\n- Checking enrichment fields are properly applied\n- Development/debugging taxonomy setup\n\n\ud83d\udcda FOR PRODUCTION ENRICHMENT:\n\nAutomatic (during ingestion):\n 1. Create taxonomy: POST /taxonomies\n 2. Attach to collection: PUT /collections/{id} with taxonomy_applications field\n 3. Ingest documents: Documents are automatically enriched by engine\n\nOn-the-fly (during retrieval):\n 1. Add taxonomy_join stage to retriever pipeline\n 2. Execute retriever: GET /retrievers/{id}/execute\n 3. Results include enriched documents (not persisted)\n\nSee API documentation for Collections and Retrievers for details.", "operationId": "execute_taxonomy_v1_taxonomies_execute__taxonomy_identifier__post", "deprecated": true, "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name to validate", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name to validate", "example": "tax_abc123" }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional taxonomy version (defaults to latest)", "title": "Version" }, "description": "Optional taxonomy version (defaults to latest)", "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExecuteTaxonomyRequest" }, { "type": "object", "additionalProperties": true } ], "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_identifier}/execute": { "post": { "tags": [ "Taxonomies" ], "summary": "Test taxonomy configuration (validation only)", "description": "\u26a0\ufe0f VALIDATION ENDPOINT ONLY - Not for production enrichment!", "operationId": "execute_taxonomy_v1_taxonomies__taxonomy_identifier__execute_post", "parameters": [ { "name": "taxonomy_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Taxonomy ID or name to validate", "title": "Taxonomy Identifier" }, "description": "Taxonomy ID or name to validate", "example": "tax_abc123" }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional taxonomy version (defaults to latest)", "title": "Version" }, "description": "Optional taxonomy version (defaults to latest)", "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ExecuteTaxonomyRequest" }, { "type": "object", "additionalProperties": true } ], "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/transitions": { "post": { "tags": [ "Taxonomy Analytics" ], "summary": "Compute step transition analytics", "description": "Analyze how documents progress from one taxonomy step to another.\n\nThis endpoint computes conversion rates, duration statistics, and predictor lifts\nfor documents transitioning between taxonomy labels.\n\n## Use Cases\n\n**Email Thread Analysis:**\n- Question: How long from \"inquiry\" to \"closed_won\"?\n- Question: What % of inquiries result in sales?\n- Question: Which sender domains have highest conversion?\n\n**Content Workflow Tracking:**\n- Question: Conversion rate from \"draft\" to \"published\"?\n- Question: How long does content stay in review?\n- Question: Which authors publish fastest?\n\n**Safety Compliance Monitoring:**\n- Question: Time from violation detection to resolution?\n- Question: Success rate for remediation efforts?\n\n## Requirements\n\n- Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`)\n- Collection must contain documents enriched with this taxonomy\n- Documents must have timestamp and sequence grouping fields configured\n\n## Returns\n\n**Conversion Metrics:**\n- `count`: Total sequences starting at from_step\n- `converted`: Number reaching to_step\n- `conversion_rate`: Percentage that converted\n\n**Duration Statistics (if converted > 0):**\n- `mean`, `median`: Average and middle duration\n- `p90`, `p95`: 90th and 95th percentile durations\n- `std_dev`, `min`, `max`: Distribution statistics\n\n**Top Predictors:**\n- Covariates with highest impact on conversion\n- Lift values (>1.0 = increases conversion, <1.0 = decreases)\n- Statistical significance via minimum support threshold\n\n## Example Request\n\n```json\n{\n \"collection_id\": \"col_emails\",\n \"taxonomy_id\": \"tax_sales_stages\",\n \"from_step\": \"inquiry\",\n \"to_step\": \"closed_won\",\n \"max_window_days\": 90,\n \"min_support\": 10\n}\n```\n\n## Example Response\n\n```json\n{\n \"from_step\": \"inquiry\",\n \"to_step\": \"closed_won\",\n \"count\": 1000,\n \"converted\": 350,\n \"conversion_rate\": 0.35,\n \"durations_sec\": {\n \"mean\": 432000.0,\n \"median\": 345600.0,\n \"p50\": 345600.0,\n \"p90\": 691200.0,\n \"p95\": 864000.0\n },\n \"top_predictors\": [\n {\n \"field\": \"Sender Domain\",\n \"value\": \"enterprise.com\",\n \"count\": 150,\n \"conversion_rate\": 0.75,\n \"lift\": 2.14\n }\n ]\n}\n```", "operationId": "compute_step_transitions_v1_taxonomies__taxonomy_id__analytics_transitions_post", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepTransitionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepTransitionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/paths": { "post": { "tags": [ "Taxonomy Analytics" ], "summary": "Analyze multi-step transition paths", "description": "Discover the most common multi-step paths documents take between two taxonomy steps.\n\nUnlike the `/transitions` endpoint which only analyzes direct A\u2192B transitions,\nthis endpoint reveals the intermediate steps documents actually take.\n\n## Use Cases\n\n**Email Thread Analysis:**\n- Question: What paths do emails take from \"inquiry\" to \"closed_won\"?\n- Discover: Some go inquiry \u2192 followup \u2192 proposal \u2192 closed_won\n- Discover: Others skip steps: inquiry \u2192 proposal \u2192 closed_won\n- Discover: Fast track: inquiry \u2192 closed_won\n\n**Content Editorial Paths:**\n- Question: Common paths from \"draft\" to \"published\"?\n- Discover: draft \u2192 review \u2192 edit \u2192 review \u2192 published\n- Discover: draft \u2192 review \u2192 published (expedited)\n- Discover: Paths that loop back (draft \u2192 review \u2192 draft \u2192 review)\n\n**Compliance Resolution Paths:**\n- Question: How do violations get resolved?\n- Discover: violation \u2192 investigated \u2192 remediated \u2192 resolved\n- Discover: violation \u2192 false_positive \u2192 closed\n- Discover: Escalation paths: violation \u2192 escalated \u2192 legal_review \u2192 resolved\n\n## Requirements\n\n- Taxonomy must have `step_analytics` configured\n- Collection must contain documents with timestamp and sequence_id fields\n\n## Returns\n\n**Completion Metrics:**\n- `total_sequences`: Sequences starting at from_step\n- `completed_sequences`: Number reaching to_step\n- `completion_rate`: Percentage that completed\n\n**Paths (sorted by frequency):**\n- `path`: Ordered sequence of steps\n- `count`: Number of sequences following this path\n- `percentage`: Percentage of completing sequences\n- `avg_duration_sec`: Average time for this path\n\n## Example Request\n\n```json\n{\n \"collection_id\": \"col_emails\",\n \"taxonomy_id\": \"tax_sales_stages\",\n \"from_step\": \"inquiry\",\n \"to_step\": \"closed_won\",\n \"max_path_length\": 10,\n \"min_support\": 5\n}\n```\n\n## Example Response\n\n```json\n{\n \"from_step\": \"inquiry\",\n \"to_step\": \"closed_won\",\n \"total_sequences\": 1000,\n \"completed_sequences\": 350,\n \"completion_rate\": 0.35,\n \"paths\": [\n {\n \"path\": [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],\n \"count\": 120,\n \"percentage\": 34.3,\n \"avg_duration_sec\": 604800.0\n },\n {\n \"path\": [\"inquiry\", \"proposal\", \"closed_won\"],\n \"count\": 90,\n \"percentage\": 25.7,\n \"avg_duration_sec\": 432000.0\n },\n {\n \"path\": [\"inquiry\", \"closed_won\"],\n \"count\": 70,\n \"percentage\": 20.0,\n \"avg_duration_sec\": 172800.0\n }\n ]\n}\n```\n\n## Path Interpretation\n\n**Length Analysis:**\n- Shorter paths indicate efficient progression\n- Longer paths may indicate complexity or bottlenecks\n- Loops (repeated steps) indicate rework or revisions\n\n**Duration Analysis:**\n- Compare avg_duration_sec across paths\n- Shorter paths may not always be faster\n- Identify optimization opportunities\n\n**Frequency Analysis:**\n- High-percentage paths are \"happy paths\"\n- Low-percentage paths may be edge cases or exceptions\n- Missing expected paths indicate drop-off points", "operationId": "analyze_transition_paths_v1_taxonomies__taxonomy_id__analytics_paths_post", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathAnalysisRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathAnalysisResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/available-steps": { "get": { "tags": [ "Taxonomy Analytics" ], "summary": "Get Available Steps", "description": "Get all available steps for a taxonomy and collection.\n\nThis endpoint discovers what steps exist in your analytics data by querying\nthe ClickHouse taxonomy_events table. Use this before querying transitions\nor paths to understand what step values you can use.\n\n**Use Cases:**\n- Discover available steps before querying analytics\n- Validate step names (avoid typos in from_step/to_step)\n- See which steps have the most events\n- Check data freshness (first_seen/last_seen timestamps)\n\n**Example Usage:**\n```python\n# 1. Get available steps\nGET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails\n\n# Response:\n{\n \"taxonomy_id\": \"tax_sales\",\n \"collection_id\": \"col_emails\",\n \"total_events\": 5432,\n \"total_sequences\": 1000,\n \"steps\": [\n {\"step_key\": \"inquiry\", \"event_count\": 1000, ...},\n {\"step_key\": \"followup\", \"event_count\": 450, ...},\n {\"step_key\": \"closed_won\", \"event_count\": 350, ...}\n ]\n}\n\n# 2. Use discovered steps in transition query\nPOST /v1/taxonomies/tax_sales/analytics/transitions\n{\n \"collection_id\": \"col_emails\",\n \"from_step\": \"inquiry\", # From available steps\n \"to_step\": \"closed_won\" # From available steps\n}\n```\n\nArgs:\n request: FastAPI request object (contains tenant context)\n taxonomy_id: Taxonomy ID to query\n collection_id: Collection ID for filtering events\n\nReturns:\n AvailableStepsResponse with all steps sorted by event count (descending)\n\nRaises:\n NotFoundError: If taxonomy not found\n ValidationError: If unable to query ClickHouse", "operationId": "get_available_steps_v1_taxonomies__taxonomy_id__analytics_available_steps_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "collection_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Collection ID to analyze", "title": "Collection Id" }, "description": "Collection ID to analyze" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableStepsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/runs": { "get": { "tags": [ "Taxonomy Analytics" ], "summary": "List taxonomy analytics run history", "description": "List previously executed step-analytics runs (transitions and paths) for a taxonomy, newest-executed first. Runs are de-duplicated by their parameters, so re-running the same analysis updates the existing entry and bumps its run_count instead of creating a duplicate.", "operationId": "list_analytics_runs_v1_taxonomies__taxonomy_id__analytics_runs_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "analysis_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/AnalysisType" }, { "type": "null" } ], "description": "Filter by analysis type (transitions or paths)", "title": "Analysis Type" }, "description": "Filter by analysis type (transitions or paths)" }, { "name": "collection_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by collection ID", "title": "Collection Id" }, "description": "Filter by collection ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed)", "default": 1, "title": "Page" }, "description": "Page number (1-indexed)" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page", "default": 20, "title": "Page Size" }, "description": "Items per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyAnalyticsRunListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/runs/{run_id}": { "get": { "tags": [ "Taxonomy Analytics" ], "summary": "Get a taxonomy analytics run", "description": "Retrieve a single persisted analytics run (its parameters and stored result) so it can be reviewed or re-run.", "operationId": "get_analytics_run_v1_taxonomies__taxonomy_id__analytics_runs__run_id__get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyAnalyticsRun" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/taxonomies/{taxonomy_id}/analytics/runs/{run_id}/rerun": { "post": { "tags": [ "Taxonomy Analytics" ], "summary": "Re-run a stored taxonomy analytics run", "description": "Re-execute a previously persisted analytics run using its stored parameters and return the FRESH result. The stored run is updated in place with the new result (run_count is incremented).", "operationId": "rerun_analytics_run_v1_taxonomies__taxonomy_id__analytics_runs__run_id__rerun_post", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/StepTransitionResponse" }, { "$ref": "#/components/schemas/PathAnalysisResponse" } ], "title": "Response Rerun Analytics Run V1 Taxonomies Taxonomy Id Analytics Runs Run Id Rerun Post" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts": { "post": { "tags": [ "Alerts" ], "summary": "Create Alert", "description": "Create a new alert that monitors document ingestion and sends notifications.\n\n Alerts attach retrievers to collections. When new documents are ingested,\n the alert runs the retriever and sends notifications if matches are found.\n\n **Key Components:**\n - `retriever_id`: References a retriever that defines query logic (filters, scoring, limits)\n - `notification_config`: Defines where to send notifications (webhook, Slack, email)\n\n **Note:** The retriever owns all query semantics. The alert's job is simply\n to run the retriever and notify if results exist.", "operationId": "create_alert_v1_alerts_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Alerts" ], "summary": "List Alerts (GET alias for POST /list).", "description": "List alerts with pagination and filtering.", "operationId": "list_alerts_v1_alerts_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/{alert_identifier}": { "get": { "tags": [ "Alerts" ], "summary": "Get Alert", "description": "Get an alert by ID (alt_...) or name.", "operationId": "get_alert_v1_alerts__alert_identifier__get", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Alerts" ], "summary": "Update Alert", "description": "Partially update an alert's configuration.\n\n **All fields are optional** - provide only what you want to update.\n\n Unlike taxonomies, alerts can be fully updated including:\n - `name`: Rename the alert\n - `description`: Update documentation\n - `retriever_id`: Change the retriever\n - `notification_config`: Update notification channels\n - `enabled`: Enable/disable the alert\n - `metadata`: Update custom metadata", "operationId": "patch_alert_v1_alerts__alert_identifier__patch", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAlertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Alerts" ], "summary": "Delete Alert", "description": "Delete an alert and its execution history.\n\n This operation:\n - Removes the alert from MongoDB\n - Deletes all execution history for this alert\n - Does NOT affect the referenced retriever", "operationId": "delete_alert_v1_alerts__alert_identifier__delete", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/list": { "post": { "tags": [ "Alerts" ], "summary": "List Alerts", "description": "List all alerts in the namespace with optional filtering and pagination.\n\n **Filtering:**\n - Use `search` for wildcard text search across alert_id, name, description\n - Use `filters` for structured queries\n\n **Sorting:**\n - Default: created_at descending (newest first)", "operationId": "list_alerts_v1_alerts_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/{alert_identifier}/executions": { "get": { "tags": [ "Alerts" ], "summary": "List Alert Executions", "description": "List execution history for a specific alert.", "operationId": "list_alert_executions_v1_alerts__alert_identifier__executions_get", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertExecutionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/{alert_identifier}/results": { "get": { "tags": [ "Alerts" ], "summary": "Get Latest Alert Result", "description": "Get the most recent execution result for an alert. Use this endpoint to poll for alert results without a webhook. Returns the latest execution with match details, or 404 if the alert has never executed.", "operationId": "get_latest_result_v1_alerts__alert_identifier__results_get", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertExecutionResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/executions": { "get": { "tags": [ "Alerts" ], "summary": "List All Executions", "description": "List execution history for all alerts in the namespace.", "operationId": "list_all_executions_v1_alerts_executions_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertExecutionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/alerts/executions/{execution_id}": { "get": { "tags": [ "Alerts" ], "summary": "Get Alert Execution", "description": "Get a single alert execution result by execution ID. Use this to poll for alert results without needing a webhook.", "operationId": "get_execution_v1_alerts_executions__execution_id__get", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Execution ID (exec_...)", "title": "Execution Id" }, "description": "Execution ID (exec_...)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertExecutionResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/organizations/alerts": { "post": { "tags": [ "Alerts" ], "summary": "Create Org-Scoped Alert", "description": "Create an organization-level alert that applies across namespaces via its `namespace_selector` (all or a selected set). Use this for system alerts (collection/batch/retriever health) that should cover the whole org rather than a single namespace.", "operationId": "create_org_alert_v1_organizations_alerts_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Alerts" ], "summary": "List Org-Scoped Alerts (GET alias for POST /list).", "description": "List org-scoped alerts with pagination and filtering.", "operationId": "list_org_alerts_v1_organizations_alerts_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/alerts/list": { "post": { "tags": [ "Alerts" ], "summary": "List Org-Scoped Alerts", "description": "List all organization-level alerts (scoped by internal_id).", "operationId": "list_org_alerts_v1_organizations_alerts_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/organizations/alerts/{alert_identifier}": { "get": { "tags": [ "Alerts" ], "summary": "Get Org-Scoped Alert", "description": "Get an org-scoped alert by ID (alt_...) or name.", "operationId": "get_org_alert_v1_organizations_alerts__alert_identifier__get", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Alerts" ], "summary": "Update Org-Scoped Alert", "description": "Partially update an org-scoped alert (e.g. enable/disable, channels).", "operationId": "patch_org_alert_v1_organizations_alerts__alert_identifier__patch", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAlertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Alerts" ], "summary": "Delete Org-Scoped Alert", "description": "Delete an org-scoped alert.", "operationId": "delete_org_alert_v1_organizations_alerts__alert_identifier__delete", "parameters": [ { "name": "alert_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Alert ID (alt_...) or name", "title": "Alert Identifier" }, "description": "Alert ID (alt_...) or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/annotations": { "post": { "tags": [ "Annotations" ], "summary": "Create Annotation", "description": "Record a human decision on a document.", "operationId": "create_annotation_v1_annotations_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/annotations/list": { "post": { "tags": [ "Annotations" ], "summary": "List Annotations", "description": "Query annotations with optional filters.", "operationId": "list_annotations_v1_annotations_list_post", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Skip" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnnotationsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnnotationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/annotations/stats": { "get": { "tags": [ "Annotations" ], "summary": "Annotation Stats", "description": "Aggregate annotation counts grouped by label.", "operationId": "annotation_stats_v1_annotations_stats_get", "parameters": [ { "name": "document_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Document Id" } }, { "name": "collection_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Collection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationStatsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/annotations/bulk": { "post": { "tags": [ "Annotations" ], "summary": "Bulk Annotations", "description": "Create, update, and/or delete annotations in a single call.\n\nEach operation is independent \u2014 a failure in one does not roll back the others.\nMaximum 1000 operations per type (creates, updates, deletes).", "operationId": "bulk_annotations_v1_annotations_bulk_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAnnotationsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAnnotationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/annotations/{annotation_id}": { "get": { "tags": [ "Annotations" ], "summary": "Get Annotation", "description": "Get a single annotation by ID.", "operationId": "get_annotation_v1_annotations__annotation_id__get", "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Annotations" ], "summary": "Patch Annotation", "description": "Update an existing annotation (label, confidence, reasoning, payload).", "operationId": "patch_annotation_v1_annotations__annotation_id__patch", "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAnnotationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Annotations" ], "summary": "Delete Annotation", "description": "Delete an annotation.", "operationId": "delete_annotation_v1_annotations__annotation_id__delete", "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Annotation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Create Cluster", "description": "Create a new cluster configuration and output collection.\n\n This endpoint:\n 1. Creates cluster metadata\n 2. Creates output collection for cluster documents\n 3. Returns cluster metadata with output_collection_id\n\n The cluster can then be executed via POST /v1/clusters/{id}/execute", "operationId": "create_cluster_v1_clusters_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClusterRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterMetadata" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Clusters" ], "summary": "List Clusters (GET)", "description": "REST-convention listing endpoint. Equivalent to ``POST /v1/clusters/list``\n with no filters or sort. Use the POST variant when you need filters,\n sort, or search.", "operationId": "list_clusters_get_v1_clusters_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search query string", "title": "Search" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClustersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/execute": { "post": { "tags": [ "Clusters" ], "summary": "Execute Clustering", "description": "Execute clustering on a specific cluster.\n\n This endpoint:\n 1. Validates the cluster exists\n 2. Queues clustering job via Celery\n 3. Returns task_id immediately (non-blocking)\n 4. Celery prepares data and submits to Engine\n 5. Monitor progress via GET /v1/tasks/{task_id}\n\n Flow:\n - API: Receives request\n - Celery: Fetches documents, creates parquet, uploads to S3\n - Engine: Runs Ray job on parquet data\n - Status: Automatically updates cluster when complete\n\n Use GET /v1/clusters/{id}/executions to retrieve results.\n\n Optional body (`ExecuteClusterByIdRequest`) accepts a `filters` override\n that applies to this execution only and is not persisted on the cluster.", "operationId": "execute_clustering_v1_clusters__cluster_id__execute_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID to execute", "title": "Cluster Id" }, "description": "Cluster ID to execute" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteClusterByIdRequest", "description": "Optional per-execution overrides (e.g. filter override)." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/groups": { "get": { "tags": [ "Clusters" ], "summary": "List Cluster Groups", "description": "Get all cluster groups with labels, summaries, and document counts from the latest execution.", "operationId": "get_cluster_groups_v1_clusters__cluster_id__groups_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterGroupsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_identifier}": { "get": { "tags": [ "Clusters" ], "summary": "Get Cluster", "description": "Retrieve a cluster by ID or name.\n\n Returns cluster metadata including:\n - Configuration (cluster_type, algorithm, parameters)\n - Output collection information (output_collection_id, output_collection_name)\n - Execution results (num_clusters, num_documents_clustered, status)\n - Timestamps and metadata", "operationId": "get_cluster_v1_clusters__cluster_identifier__get", "parameters": [ { "name": "cluster_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID or name", "title": "Cluster Identifier" }, "description": "Cluster ID or name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterMetadata" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Clusters" ], "summary": "Partially Update Cluster", "description": "This endpoint partially updates a cluster (PATCH operation).\n Only provided fields will be updated. At minimum, metadata can always be updated.\n Immutable fields like cluster_id, status, and computed fields cannot be modified.", "operationId": "patch_cluster_v1_clusters__cluster_identifier__patch", "parameters": [ { "name": "cluster_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID or name", "title": "Cluster Identifier" }, "description": "Cluster ID or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchClusterRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}": { "delete": { "tags": [ "Clusters" ], "summary": "Delete Cluster", "description": "This endpoint deletes a cluster and all its resources including:\n - Running Ray jobs (cancels active jobs)\n - Cluster triggers\n - Execution history (clustering_results)\n - S3 artifacts (parquet files, documents, members)\n - Related tasks\n - Clustering jobs\n - MongoDB cluster metadata\n - Output collections created by the cluster (by default)\n\n By default, output collections created by the cluster are cascade-deleted\n along with the cluster. Pass `cascade_output_collections=false` to preserve\n them (useful when the cluster output documents were enriched / promoted\n into user-managed data).\n\n The deletion is performed synchronously and returns when complete.", "operationId": "delete_cluster_v1_clusters__cluster_id__delete", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "cascade_output_collections", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true (default), the cluster's output collections are deleted alongside the cluster. Set to false to preserve them.", "default": true, "title": "Cascade Output Collections" }, "description": "When true (default), the cluster's output collections are deleted alongside the cluster. Set to false to preserve them." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/list": { "post": { "tags": [ "Clusters" ], "summary": "List Clusters", "description": "This endpoint allows you to list clusters.", "operationId": "list_clusters_v1_clusters_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClustersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClustersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/enrich": { "post": { "tags": [ "Clusters" ], "summary": "Apply Cluster Enrichment", "description": "Apply clustering enrichments to a collection via engine.", "operationId": "apply_cluster_enrichment_v1_clusters_enrich_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyClusterEnrichmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusteringEnrichmentResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/visualization": { "get": { "tags": [ "Clusters" ], "summary": "Cluster Visualization Data", "description": "Return sampled visualization coordinates for rendering a cluster scatter plot. Returns all centroids plus a random sample of members (default 10,000). Only the fields needed for rendering are returned, keeping the payload small.", "operationId": "get_cluster_visualization_v1_clusters__cluster_id__visualization_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "max_points", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000000, "minimum": 1, "description": "Max member points to return", "default": 10000, "title": "Max Points" }, "description": "Max member points to return" }, { "name": "centroids_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return only centroid points (fast initial load for large clusters)", "default": false, "title": "Centroids Only" }, "description": "Return only centroid points (fast initial load for large clusters)" }, { "name": "compact", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return members as parallel arrays (x[], y[], z[], cluster_ids[], document_ids[]) instead of array-of-objects. ~60% smaller JSON for large point counts. Centroids are still returned as objects.", "default": false, "title": "Compact" }, "description": "Return members as parallel arrays (x[], y[], z[], cluster_ids[], document_ids[]) instead of array-of-objects. ~60% smaller JSON for large point counts. Centroids are still returned as objects." }, { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Return the scatter for a SPECIFIC run instead of the current one. The output collection only ever holds the latest run's points, so per-run points are served from that run's stored artifact. Used by Studio's run-compare; omit for the current run (default).", "title": "Run Id" }, "description": "Return the scatter for a SPECIFIC run instead of the current one. The output collection only ever holds the latest run's points, so per-run points are served from that run's stored artifact. Used by Studio's run-compare; omit for the current run (default)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers": { "post": { "tags": [ "Cluster Triggers" ], "summary": "Create Cluster Trigger", "description": "Create a new trigger for automated cluster execution.\n\n Supports multiple trigger types:\n - **cron**: Execute at specific times using cron expressions\n - **interval**: Execute at fixed intervals\n - **event**: Execute when specific events occur (e.g., documents added)\n - **conditional**: Execute when conditions are met (e.g., drift threshold)", "operationId": "create_trigger_v1_clusters_triggers_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__CreateTriggerRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers/list": { "post": { "tags": [ "Cluster Triggers" ], "summary": "List Cluster Triggers", "description": "List cluster triggers with filters and pagination.", "operationId": "list_triggers_v1_clusters_triggers_list_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__ListTriggersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__ListTriggersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers/{trigger_id}": { "get": { "tags": [ "Cluster Triggers" ], "summary": "Get Cluster Trigger", "description": "Get a cluster trigger by ID.", "operationId": "get_trigger_v1_clusters_triggers__trigger_id__get", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Cluster Triggers" ], "summary": "Update Cluster Trigger", "description": "Update a cluster trigger.\n\n Allowed updates:\n - schedule_config: Modify trigger schedule\n - description: Update description\n - status: Change status (use pause/resume endpoints instead)\n\n Not allowed:\n - trigger_type: Must delete and recreate\n - cluster_id: Immutable\n - execution_config: Immutable", "operationId": "update_trigger_v1_clusters_triggers__trigger_id__patch", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__UpdateTriggerRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Cluster Triggers" ], "summary": "Delete Cluster Trigger", "description": "Delete a cluster trigger (soft delete).", "operationId": "delete_trigger_v1_clusters_triggers__trigger_id__delete", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers/{trigger_id}/pause": { "post": { "tags": [ "Cluster Triggers" ], "summary": "Pause Cluster Trigger", "description": "Pause trigger execution. Paused triggers retain configuration but do not execute.", "operationId": "pause_trigger_v1_clusters_triggers__trigger_id__pause_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers/{trigger_id}/resume": { "post": { "tags": [ "Cluster Triggers" ], "summary": "Resume Cluster Trigger", "description": "Resume paused trigger. Next execution time is recalculated from current time.", "operationId": "resume_trigger_v1_clusters_triggers__trigger_id__resume_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/triggers/{trigger_id}/history": { "post": { "tags": [ "Cluster Triggers" ], "summary": "Get Trigger Execution History", "description": "Get execution history for a trigger with pagination.", "operationId": "get_trigger_history_v1_clusters_triggers__trigger_id__history_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerHistoryRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__clusters__triggers__models__TriggerHistoryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions": { "get": { "tags": [ "Cluster Executions" ], "summary": "Get Latest Cluster Execution", "description": "Get the most recent execution results for a cluster.\n\n Returns execution metadata including:\n - Execution status (pending, processing, completed, failed)\n - Clustering metrics (silhouette score, Davies-Bouldin index, etc.)\n - Number of clusters found and documents processed\n - Centroid information with labels and summaries\n - Execution timestamps\n\n Useful for:\n - Displaying cluster statistics in dashboards\n - Showing cluster quality metrics to users\n - Rendering cluster labels and summaries in the UI\n - Tracking execution status and errors", "operationId": "get_cluster_execution_v1_clusters__cluster_id__executions_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "include_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in: vectors are large (~120KB for 15x1024-dim centroids), so they are omitted from the response entirely unless this is true. Lets clients run vector-input searches with a centroid as the query even when the centroid document is no longer in the vector store.", "default": false, "title": "Include Vectors" }, "description": "Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in: vectors are large (~120KB for 15x1024-dim centroids), so they are omitted from the response entirely unless this is true. Lets clients run vector-input searches with a centroid as the query even when the centroid document is no longer in the vector store." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ClusterExecutionResult" }, { "type": "null" } ], "title": "Response Get Cluster Execution V1 Clusters Cluster Id Executions Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/{run_id}": { "get": { "tags": [ "Cluster Executions" ], "summary": "Get Specific Cluster Execution", "description": "Get a specific execution by run ID.\n\n Returns detailed execution information for a particular clustering run,\n allowing you to review historical executions and compare results over time.", "operationId": "get_cluster_execution_by_run_v1_clusters__cluster_id__executions__run_id__get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run ID", "title": "Run Id" }, "description": "Run ID" }, { "name": "include_vectors", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in; see GET /{cluster_id}/executions for details.", "default": false, "title": "Include Vectors" }, "description": "Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in; see GET /{cluster_id}/executions for details." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterExecutionResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/list": { "post": { "tags": [ "Cluster Executions" ], "summary": "List Cluster Execution History", "description": "List execution history for a cluster with pagination, filtering, sorting, and search.\n\n Returns all historical executions for the specified cluster, including:\n - Execution status (pending, processing, completed, failed)\n - Clustering metrics (silhouette score, Davies-Bouldin index, etc.)\n - Number of clusters found and documents processed\n - Execution timestamps and duration\n - Centroid information\n\n Supports:\n - **Filtering**: Filter by status, date range, metrics, etc.\n - **Sorting**: Sort by created_at, execution time, metrics\n - **Search**: Full-text search across execution metadata\n - **Pagination**: Limit and offset for large result sets\n\n Use cases:\n - View all past executions for a cluster\n - Compare metrics across runs\n - Track execution history over time\n - Debug failed executions\n - Analyze clustering performance trends", "operationId": "list_cluster_executions_v1_clusters__cluster_id__executions_list_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClusterExecutionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClusterExecutionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/{run_id}/export": { "get": { "tags": [ "Cluster Executions" ], "summary": "Export Cluster Run Data (CSV / Parquet)", "description": "One-click export of a clustering run's data \u2014 the exact rows behind the\n visualization (one row per member plus one per centroid: document id,\n cluster id and current label, x/y[/z] layout coordinates, per-cluster\n stats, and any custom LLM fields).\n\n Formats:\n - **`format=parquet`** (default): returns JSON with a short-lived\n presigned download URL for the run's `cluster_documents.parquet`\n artifact \u2014 the full-fidelity file (includes centroid vectors), any\n size. Download it promptly; the URL expires.\n - **`format=csv`**: streams a spreadsheet-friendly CSV conversion \u2014\n stable column order, current (renamed) cluster labels, no raw vectors.\n Capped at 100,000 rows; bigger runs get a clear 413 pointing to\n parquet. Scope to one cluster with `cluster_label` (accepts the run's\n cluster id like `cl_3` OR its current label).\n\n Exports are strictly per-run: the run you pass is the run you get.\n Runs that completed before artifacts existed, failed before the export\n step, or whose artifacts have aged out of object storage return 404\n with a message saying exactly what's missing.", "operationId": "export_cluster_execution_v1_clusters__cluster_id__executions__run_id__export_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run ID whose data to export", "title": "Run Id" }, "description": "Run ID whose data to export" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(parquet|csv)$", "description": "Export format: 'parquet' returns a presigned download URL (JSON), 'csv' streams the converted file", "default": "parquet", "title": "Format" }, "description": "Export format: 'parquet' returns a presigned download URL (JSON), 'csv' streams the converted file" }, { "name": "cluster_label", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CSV only: restrict rows to one cluster \u2014 accepts the run's cluster id (e.g. 'cl_3') or its current label", "title": "Cluster Label" }, "description": "CSV only: restrict rows to one cluster \u2014 accepts the run's cluster id (e.g. 'cl_3') or its current label" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/{run_id}/labels": { "patch": { "tags": [ "Cluster Executions" ], "summary": "Rename Cluster Labels (Per-Execution)", "description": "Rename cluster labels for a single execution \u2014 no re-run required.\n\n Entries merge into the execution record's `label_overrides` map\n (per-key upsert): a non-empty value sets/replaces the override for that\n cluster_id, an empty string deletes it (restoring the original LLM/auto\n label). Overrides are applied server-side wherever labels are read \u2014\n execution GETs (`centroids[].label`) and the cluster visualization\n endpoint (`cluster_label` on centroid points) \u2014 so all clients agree.\n\n Overrides are per-run because cluster ids (`cl_0`, `cl_1`, ...) are\n assigned per-run: a rename on one execution never leaks onto another.\n\n Example body: `{\"labels\": {\"cl_0\": \"Gadget Reviews\", \"cl_2\": \"\"}}`\n (renames cl_0, deletes any override on cl_2).", "operationId": "patch_execution_labels_v1_clusters__cluster_id__executions__run_id__labels_patch", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run ID whose labels to rename", "title": "Run Id" }, "description": "Run ID whose labels to rename" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchExecutionLabelsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchExecutionLabelsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/{run_id}/name": { "patch": { "tags": [ "Cluster Executions" ], "summary": "Name an Execution Run", "description": "Set (or clear) a human-friendly name on a single execution run \u2014 no\n re-run required.\n\n A non-empty value sets/replaces the run's `run_name`; an empty string\n clears it, restoring the unnamed (run_id-only) state. Names are trimmed\n and capped at 120 characters. The name is persisted on the execution\n record and returned by execution GET/LIST responses (`run_name`,\n omitted entirely while unnamed), so run selectors and execution-history\n views can show 'July tuning baseline' instead of `run_a8e2709532...`.\n\n Sibling of PATCH `.../executions/{run_id}/labels`: each display field\n gets its own strict single-purpose PATCH rather than a general\n execution PATCH, because execution results themselves are immutable.\n\n Example body: `{\"run_name\": \"July tuning baseline\"}` (or\n `{\"run_name\": \"\"}` to clear).", "operationId": "patch_execution_run_name_v1_clusters__cluster_id__executions__run_id__name_patch", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run ID to name", "title": "Run Id" }, "description": "Run ID to name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchExecutionRunNameRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchExecutionRunNameResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/clusters/{cluster_id}/executions/{run_id}/cancel": { "post": { "tags": [ "Cluster Executions" ], "summary": "Cancel Execution", "description": "Cancel a pending or processing cluster execution.\n\n This cancels the Ray job (if running) and marks the execution as CANCELED.\n Useful for:\n - Cleaning up orphaned executions where the Ray job was never submitted\n - Stopping long-running clustering jobs\n - Handling executions stuck in pending/processing state\n\n Only works for executions in 'pending' or 'processing' status.\n Returns an error if the execution is already 'completed', 'failed', or 'canceled'.", "operationId": "cancel_execution_v1_clusters__cluster_id__executions__run_id__cancel_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Cluster ID", "title": "Cluster Id" }, "description": "Cluster ID" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run ID to cancel", "title": "Run Id" }, "description": "Run ID to cancel" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers": { "post": { "tags": [ "Triggers" ], "summary": "Create Trigger", "description": "Create a new trigger for scheduled job execution.\n\n **Action Types:**\n - `cluster`: Execute clustering on a cluster definition\n - `taxonomy_enrichment`: Apply taxonomy enrichment to a collection\n\n **Schedule Types:**\n - `cron`: Execute at specific times using cron expressions (e.g., \"0 2 * * *\" for daily at 2am)\n - `interval`: Execute at fixed intervals (e.g., every 6 hours)\n - `event`: Execute when specific events occur (e.g., after 100 documents added)\n - `conditional`: Execute when conditions are met (e.g., drift threshold exceeded)\n\n **Examples:**\n\n Cluster trigger (daily at 2am):\n ```json\n {\n \"action_type\": \"cluster\",\n \"action_config\": {\"cluster_id\": \"clust_abc123\"},\n \"trigger_type\": \"cron\",\n \"schedule_config\": {\"cron_expression\": \"0 2 * * *\", \"timezone\": \"UTC\"},\n \"description\": \"Daily clustering at 2am\"\n }\n ```\n\n Taxonomy enrichment trigger (every 6 hours):\n ```json\n {\n \"action_type\": \"taxonomy_enrichment\",\n \"action_config\": {\n \"taxonomy_id\": \"tax_products\",\n \"collection_id\": \"col_inventory\",\n \"batch_size\": 1000\n },\n \"trigger_type\": \"interval\",\n \"schedule_config\": {\"interval_seconds\": 21600},\n \"description\": \"Re-enrich products every 6 hours\"\n }\n ```", "operationId": "create_trigger_v1_triggers_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__CreateTriggerRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "get": { "tags": [ "Triggers" ], "summary": "List Triggers (GET alias for POST /list).", "description": "List triggers with filters and pagination.", "operationId": "list_triggers_v1_triggers_get", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__ListTriggersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__ListTriggersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/list": { "post": { "tags": [ "Triggers" ], "summary": "List Triggers", "description": "List triggers with filters and pagination.\n\n **Filters:**\n - `action_type`: Filter by action type (cluster, taxonomy_enrichment)\n - `trigger_type`: Filter by trigger type (cron, interval, event, conditional)\n - `status`: Filter by status (active, paused, disabled, failed)\n - `resource_id`: Filter by resource ID (cluster_id or taxonomy_id)", "operationId": "list_triggers_v1_triggers_list_post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__ListTriggersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__ListTriggersResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/{trigger_id}": { "get": { "tags": [ "Triggers" ], "summary": "Get Trigger", "description": "Get a trigger by ID.", "operationId": "get_trigger_v1_triggers__trigger_id__get", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Triggers" ], "summary": "Update Trigger", "description": "Update a trigger.\n\n **Allowed updates:**\n - `schedule_config`: Modify trigger schedule\n - `description`: Update description\n - `status`: Change status (prefer using pause/resume endpoints)\n\n **Not allowed:**\n - `action_type`: Must delete and recreate\n - `trigger_type`: Must delete and recreate\n - `action_config`: Must delete and recreate", "operationId": "update_trigger_v1_triggers__trigger_id__patch", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__UpdateTriggerRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Triggers" ], "summary": "Delete Trigger", "description": "Delete a trigger (soft delete - sets status to disabled).", "operationId": "delete_trigger_v1_triggers__trigger_id__delete", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/{trigger_id}/pause": { "post": { "tags": [ "Triggers" ], "summary": "Pause Trigger", "description": "Pause trigger execution. Paused triggers retain configuration but do not execute.", "operationId": "pause_trigger_v1_triggers__trigger_id__pause_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/{trigger_id}/resume": { "post": { "tags": [ "Triggers" ], "summary": "Resume Trigger", "description": "Resume a paused trigger. Next execution time is recalculated from current time.", "operationId": "resume_trigger_v1_triggers__trigger_id__resume_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/{trigger_id}/execute": { "post": { "tags": [ "Triggers" ], "summary": "Execute Trigger Now", "description": "Manually execute a trigger immediately.\n\n This bypasses the schedule and executes the trigger's action right away.\n Useful for testing trigger configuration or forcing immediate execution.\n\n Returns a task response that can be used to monitor execution progress.", "operationId": "execute_trigger_now_v1_triggers__trigger_id__execute_post", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/triggers/{trigger_id}/history": { "get": { "tags": [ "Triggers" ], "summary": "Get Trigger Execution History", "description": "Get execution history for a trigger with pagination.", "operationId": "get_trigger_history_v1_triggers__trigger_id__history_get", "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Trigger ID", "title": "Trigger Id" }, "description": "Trigger ID" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Results per page", "default": 50, "title": "Limit" }, "description": "Results per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared__triggers__models__TriggerHistoryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/tools": { "get": { "tags": [ "Agent Sessions" ], "summary": "List Tools", "description": "List all available agent tools.\n\nUse this endpoint to discover available tools before creating a session.\n\nTool Categories:\n- search: Tools for searching data (execute_retriever)\n- read: Tools for reading resources (list_*, get_*)\n- create: Tools for creating resources (create_*) - requires confirmation\n- update: Tools for updating resources (update_*) - requires confirmation\n- delete: Tools for deleting resources (delete_*) - requires confirmation\n- upload: Tools for file uploads (upload_object)\n\nNote: Write operations (create, update, delete) require user confirmation\nvia the /confirmations endpoint before execution.\n\nArgs:\n request: FastAPI request with tenant context\n category: Optional filter by tool category\n\nReturns:\n ListToolsResponse with available tools\n\nExample:\n ```bash\n # List all tools\n curl -X GET http://localhost:8000/v1/agents/tools \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\"\n\n # List only search tools\n curl -X GET \"http://localhost:8000/v1/agents/tools?category=search\" \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\"\n ```", "operationId": "list_tools_v1_agents_sessions_tools_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by tool category", "title": "Category" }, "description": "Filter by tool category" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListToolsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions": { "post": { "tags": [ "Agent Sessions" ], "summary": "Create Session", "description": "Create a new agent session.\n\nA session represents a stateful conversation with an AI agent that can\ncall tools to search data, filter results, and perform multi-step reasoning.\n\nArgs:\n request: FastAPI request with tenant context\n payload: Session creation request\n\nReturns:\n CreateSessionResponse with session metadata\n\nExample:\n ```bash\n curl -X POST http://localhost:8000/v1/agents/sessions \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agent_config\": {\n \"model\": \"claude-3-5-sonnet-20241022\",\n \"temperature\": 0.7,\n \"available_tools\": [\"search_retrievers\", \"execute_retriever\"]\n },\n \"quotas\": {\n \"max_messages\": 100,\n \"max_tokens_total\": 100000\n }\n }'\n ```", "operationId": "create_session_v1_agents_sessions_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/list": { "post": { "tags": [ "Agent Sessions" ], "summary": "List Sessions", "description": "List agent sessions in the namespace.\n\nArgs:\n request: FastAPI request with tenant context\n list_request: Optional filters and sorting\n pagination: Pagination parameters\n\nReturns:\n ListSessionsResponse with session list\n\nExample:\n ```bash\n curl -X POST http://localhost:8000/v1/agents/sessions/list \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"active\"}'\n ```", "operationId": "list_sessions_v1_agents_sessions_list_post", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Limit" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "title": "Page Size" } }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 0 }, { "type": "null" } ], "title": "Offset" } }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Page" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Total" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/{session_id}": { "get": { "tags": [ "Agent Sessions" ], "summary": "Get Session", "description": "Get session metadata by ID.\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n\nReturns:\n GetSessionResponse with session metadata\n\nRaises:\n NotFoundError: If session not found\n\nExample:\n ```bash\n curl -X GET http://localhost:8000/v1/agents/sessions/ses_abc123 \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\"\n ```", "operationId": "get_session_v1_agents_sessions__session_id__get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "patch": { "tags": [ "Agent Sessions" ], "summary": "Patch Session", "description": "Update session metadata.\n\nOnly user_memory can be updated. To change agent configuration,\ncreate a new session.\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n payload: Update request\n\nReturns:\n PatchSessionResponse with update timestamp\n\nRaises:\n NotFoundError: If session not found\n\nExample:\n ```bash\n curl -X PATCH http://localhost:8000/v1/agents/sessions/ses_abc123 \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_memory\": {\n \"preferences\": {\"language\": \"en\", \"domain\": \"tech\"}\n }\n }'\n ```", "operationId": "patch_session_v1_agents_sessions__session_id__patch", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] }, "delete": { "tags": [ "Agent Sessions" ], "summary": "Terminate Session", "description": "Terminate a session and kill its actor.\n\nThis permanently ends the session and releases all associated resources.\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n\nReturns:\n TerminateSessionResponse with termination timestamp\n\nRaises:\n NotFoundError: If session not found\n\nExample:\n ```bash\n curl -X DELETE http://localhost:8000/v1/agents/sessions/ses_abc123 \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\"\n ```", "operationId": "terminate_session_v1_agents_sessions__session_id__delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminateSessionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/{session_id}/messages": { "post": { "tags": [ "Agent Sessions" ], "summary": "Send Message", "description": "Send a message to the agent and stream the response.\n\nThis endpoint streams Server-Sent Events (SSE) back to the client as\nthe agent processes the message through its workflow.\n\n## SSE Event Types\n\n**Core Events:**\n- `intent`: Intent classification result (emitted first)\n - `{intent, confidence, category, reasoning, context_scope}`\n- `thinking`: Agent is analyzing/planning\n - `{step, message}`\n- `tool_call`: Agent is calling a tool\n - `{tool_name, tool_call_id, inputs}`\n- `tool_result`: Tool execution completed\n - `{tool_name, tool_call_id, success, output, latency_ms}`\n- `token`: Response token (streaming)\n - `{content}`\n- `message`: Final response content\n - `{content, message_id, is_final}`\n- `session_name`: Auto-generated session name (first message only)\n - `{session_name}`\n- `done`: Processing complete\n - `{latency_ms, tool_calls_made, message_id, retriever_summary, data_accessed_via_retriever}`\n- `error`: Error occurred\n - `{message, recoverable}`\n\n**Retriever Events (IMPORTANT - Primary Data Pathway):**\n- `retriever_execution`: Retriever was used for data access\n - `{tool_name, execution_id, retriever_id, is_adhoc, documents_returned, latency_ms, message}`\n - Emitted whenever data is accessed via retriever (saved or ad-hoc)\n- `pipeline_config`: Ad-hoc retriever configuration\n - `{tool_name, config, message}`\n - Contains the exact pipeline config users can save as a named retriever\n\n**Retriever Summary in `done` Event:**\n```json\n{\n \"retriever_summary\": {\n \"used_retrievers\": true,\n \"retriever_count\": 2,\n \"saved_retrievers\": 1,\n \"adhoc_retrievers\": 1,\n \"total_documents\": 25,\n \"executions\": [...]\n },\n \"data_accessed_via_retriever\": true\n}\n```\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n payload: Message request\n\nReturns:\n StreamingResponse with SSE events\n\nRaises:\n NotFoundError: If session not found\n\nExample:\n ```bash\n curl -N -X POST http://localhost:8000/v1/agents/sessions/ses_abc123/messages \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Find videos about machine learning\",\n \"stream\": true\n }'\n\n # SSE Output:\n event: intent\n data: {\"intent\": \"retriever_search\", \"confidence\": 0.92, \"category\": \"retriever\"}\n\n event: thinking\n data: {\"step\": \"processing\", \"message\": \"Analyzing your request...\"}\n\n event: tool_call\n data: {\"tool_name\": \"execute_retriever\", \"tool_call_id\": \"run_abc\", \"inputs\": {...}}\n\n event: tool_result\n data: {\"tool_name\": \"execute_retriever\", \"success\": true, \"output\": {...}}\n\n event: retriever_execution\n data: {\"tool_name\": \"execute_retriever\", \"is_adhoc\": false, \"documents_returned\": 5}\n\n event: message\n data: {\"content\": \"I found 5 videos about machine learning...\", \"is_final\": true}\n\n event: done\n data: {\"latency_ms\": 1250.5, \"data_accessed_via_retriever\": true, \"retriever_summary\": {...}}\n ```", "operationId": "send_message_v1_agents_sessions__session_id__messages_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/{session_id}/confirmations/{confirmation_id}": { "post": { "tags": [ "Agent Sessions" ], "summary": "Respond To Confirmation", "description": "Respond to a pending confirmation for a write operation.\n\nWhen the agent requests a write operation (create, update, delete),\nthe stream pauses and emits a `confirmation_required` event. The user\nmust call this endpoint to approve or deny the action.\n\nAfter responding, this endpoint returns a new SSE stream that continues\nthe agent's execution from where it paused.\n\n## Confirmation Workflow\n\n1. User sends message via POST /sessions/{id}/messages\n2. Agent proposes a write operation\n3. Stream emits `confirmation_required` event with `confirmation_id`\n4. User calls this endpoint with `approved: true/false`\n5. This endpoint returns SSE stream continuing the agent's work\n6. If approved, agent executes the tool and continues\n7. If denied, agent acknowledges and continues without executing\n\n## Confirmation Expiration\n\nConfirmations expire after 5 minutes. Attempting to respond to an\nexpired confirmation returns a 400 error.\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n confirmation_id: Confirmation identifier from `confirmation_required` event\n payload: Approval/denial decision\n\nReturns:\n StreamingResponse with SSE events (continuation of agent execution)\n\nRaises:\n NotFoundError: If session or confirmation not found\n ValidationError: If confirmation already processed or expired\n\nExample:\n ```bash\n # Approve a pending action\n curl -N -X POST http://localhost:8000/v1/agents/sessions/ses_abc/confirmations/conf_xyz \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"approved\": true}'\n\n # SSE Output (continuation):\n event: tool_result\n data: {\"tool_name\": \"delete_collection\", \"success\": true, \"result\": {...}}\n\n event: token\n data: {\"content\": \"I've deleted the collection as requested.\"}\n\n event: done\n data: {}\n ```", "operationId": "respond_to_confirmation_v1_agents_sessions__session_id__confirmations__confirmation_id__post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" }, { "name": "confirmation_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Confirmation ID", "title": "Confirmation Id" }, "description": "Confirmation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/{session_id}/history": { "get": { "tags": [ "Agent Sessions" ], "summary": "Get History", "description": "Get conversation history for a session.\n\nReturns messages in chronological order (oldest first).\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n limit: Maximum messages to return (default: 50, max: 200)\n offset: Pagination offset (default: 0)\n\nReturns:\n GetHistoryResponse with message history\n\nRaises:\n NotFoundError: If session not found\n\nExample:\n ```bash\n curl -X GET \"http://localhost:8000/v1/agents/sessions/ses_abc123/history?limit=20&offset=0\" \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\"\n ```", "operationId": "get_history_v1_agents_sessions__session_id__history_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum messages to return", "default": 50, "title": "Limit" }, "description": "Maximum messages to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetHistoryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/{session_id}/feedback": { "post": { "tags": [ "Agent Sessions" ], "summary": "Submit Feedback", "description": "Submit feedback on an assistant message.\n\nWhen positive feedback is received, the conversation exchange is stored\nto memory for future context. When negative feedback is received, the\nexchange is NOT stored. This enables learning from quality interactions.\n\nArgs:\n request: FastAPI request with tenant context\n session_id: Session identifier\n payload: Feedback request\n\nReturns:\n SubmitFeedbackResponse with feedback status\n\nRaises:\n NotFoundError: If session or message not found\n\nExample:\n ```bash\n curl -X POST http://localhost:8000/v1/agents/sessions/ses_abc123/feedback \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"message_id\": \"msg_xyz789\",\n \"rating\": \"positive\",\n \"feedback_text\": \"Very helpful response!\"\n }'\n ```", "operationId": "submit_feedback_v1_agents_sessions__session_id__feedback_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Session ID", "title": "Session Id" }, "description": "Session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeedbackRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeedbackResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/agents/sessions/intent/detect": { "post": { "tags": [ "Agent Sessions" ], "summary": "Detect Intent", "description": "Detect user intent from natural language request.\n\nThis endpoint analyzes a user's request to determine whether they want to:\n- Execute queries on existing data (execution mode)\n- Create new resources/infrastructure (setup mode)\n- Or if the request is ambiguous and needs clarification\n\nIt performs keyword analysis and checks existing collections to provide\nintelligent classification and recommendations.\n\nArgs:\n request: FastAPI request with tenant context\n payload: Intent detection request with user's input\n\nReturns:\n IntentClassification with detected intent and recommendations\n\nExample:\n ```bash\n curl -X POST http://localhost:8000/v1/agents/intent/detect \\\n -H \"Authorization: Bearer {api_key}\" \\\n -H \"X-Namespace: {namespace_id}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_request\": \"I want to search videos by faces\",\n \"include_collection_analysis\": true\n }'\n ```", "operationId": "detect_intent_v1_agents_sessions_intent_detect_post", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectIntentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentClassification" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/performance": { "get": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Get Retriever Performance", "description": "Get retriever performance metrics for tuning.\n\nRetrieves time-series performance data including:\n- Query latency (P50, P95, P99)\n- Query counts\n- Result counts\n- Latency trends\n\n**Use Cases:**\n- Monitor retriever performance over time\n- Identify performance degradations\n- Compare performance across time periods\n- Establish performance baselines\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/performance?hours=24&group_by=hour\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_retriever_performance_v1_analytics_retrievers__retriever_id__performance_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date (UTC)", "title": "Start Date" }, "description": "Start date (UTC)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date (UTC)", "title": "End Date" }, "description": "End date (UTC)" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Time grouping: hour, day, week", "default": "hour", "title": "Group By" }, "description": "Time grouping: hour, day, week" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieverPerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/stages": { "get": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Get Stage Breakdown", "description": "Get stage-level performance breakdown.\n\nAnalyzes individual stage performance to identify bottlenecks:\n- Stage execution times\n- Document flow (in/out)\n- Stage-level latency distribution\n\n**Use Cases:**\n- Identify slow stages in retrieval pipeline\n- Optimize stage ordering\n- Debug pipeline bottlenecks\n- Understand document reduction rates\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/stages?hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_stage_breakdown_v1_analytics_retrievers__retriever_id__stages_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageBreakdownResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/signals": { "get": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Get Retriever Signals", "description": "Get retriever signals for interaction tuning.\n\nRetrieves fine-grained signals about retriever behavior:\n- Cache hits/misses\n- Reranking scores\n- Filter effectiveness\n- Query expansion results\n\n**Signal Types:**\n- `cache_hit`: Successful cache lookups\n- `cache_miss`: Cache misses requiring full search\n- `rerank_scores`: Reranking effectiveness metrics\n- `filter_reduction`: Pre-filter document reduction\n- `expansion_results`: Query expansion impact\n\n**Use Cases:**\n- Fine-tune retrieval parameters\n- Analyze query patterns\n- Optimize cache strategies\n- Validate optimization improvements\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/signals?signal_type=rerank_scores&limit=50\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_retriever_signals_v1_analytics_retrievers__retriever_id__signals_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "signal_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by signal type (cache_hit, rerank_scores, etc.)", "title": "Signal Type" }, "description": "Filter by signal type (cache_hit, rerank_scores, etc.)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Maximum results", "default": 100, "title": "Limit" }, "description": "Maximum results" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverSignal" }, "title": "Response Get Retriever Signals V1 Analytics Retrievers Retriever Id Signals Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/cache-performance": { "get": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Get Cache Performance", "description": "Get cache performance metrics.\n\nAnalyzes cache effectiveness including:\n- Hit/miss rates\n- Latency comparison (cache vs full search)\n- Hourly cache performance trends\n\n**Use Cases:**\n- Evaluate cache effectiveness\n- Optimize cache TTL settings\n- Monitor cache performance\n- Identify cache warming opportunities\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/cache-performance?hours=168\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_cache_performance_v1_analytics_retrievers__retriever_id__cache_performance_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CachePerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/analyze-tuning": { "post": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Analyze For Tuning", "description": "Analyze retriever and generate tuning recommendations.\n\nPerforms comprehensive analysis and generates actionable recommendations:\n- Parameter tuning suggestions\n- Cache optimization opportunities\n- Performance improvement estimates\n\n**Recommendations Include:**\n- Increase/decrease k value\n- Adjust reranking thresholds\n- Enable/optimize caching\n- Stage reordering suggestions\n\n**Use Cases:**\n- Initial retriever configuration\n- Periodic performance optimization\n- A/B testing parameter changes\n- Cost optimization\n\n**Example:**\n```bash\ncurl -X POST \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/analyze-tuning?days=7\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "analyze_for_tuning_v1_analytics_retrievers__retriever_id__analyze_tuning_post", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 7, "title": "Days" }, "description": "Days of history to analyze" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionTuningResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/retrievers/{retriever_id}/slow-queries": { "get": { "tags": [ "Analytics", "Analytics - Retrievers" ], "summary": "Get Slowest Queries", "description": "Get slowest queries for troubleshooting.\n\nIdentifies slowest-performing queries for optimization:\n- Query text\n- Execution time\n- Result counts\n- Stage breakdown\n\n**Use Cases:**\n- Identify problematic queries\n- Debug performance issues\n- Optimize query patterns\n- User experience improvements\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/retrievers/ret_abc123/slow-queries?limit=10&hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_slowest_queries_v1_analytics_retrievers__retriever_id__slow_queries_get", "parameters": [ { "name": "retriever_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Retriever Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Number of queries to return", "default": 10, "title": "Limit" }, "description": "Number of queries to return" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Slowest Queries V1 Analytics Retrievers Retriever Id Slow Queries Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/engine": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Get Engine Performance", "description": "Get engine performance metrics over time.\n\nQuery profiling data logged by the engine's profiling infrastructure.\nAll queries are automatically filtered to your namespace.\n\n**Time Range:**\n- Specify `hours` for recent history (e.g., `hours=24` for last 24 hours)\n- OR specify `start_date` and `end_date` for custom range\n- Defaults to last 24 hours if neither provided\n\n**Grouping:**\n- `minute`: High-resolution (for short time ranges)\n- `hour`: Standard resolution (default)\n- `day`: For longer time ranges\n- `week`, `month`: For historical trends\n\n**Response:**\n- Time-series metrics (avg, p50, p95, p99 latencies)\n- Summary statistics across the entire time range\n- All latencies in milliseconds\n\n**Example:**\n```bash\nGET /v1/analytics/performance/engine?hours=24&group_by=hour\n```", "operationId": "get_engine_performance_v1_analytics_performance_engine_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 720, "minimum": 1 }, { "type": "null" } ], "description": "Hours of history (alternative to date range)", "title": "Hours" }, "description": "Hours of history (alternative to date range)" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date for time range", "title": "Start Date" }, "description": "Start date for time range" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date for time range", "title": "End Date" }, "description": "End date for time range" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(minute|hour|day|week|month)$", "description": "Time grouping (minute, hour, day, week)", "default": "hour", "title": "Group By" }, "description": "Time grouping (minute, hour, day, week)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnginePerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/engine/stages": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Get Engine Stage Breakdown", "description": "Get stage-level performance breakdown.\n\nBreaks down engine performance by individual profiled stages\n(e.g., pipeline_run, generate_input_dataset, gcs_batch_upload).\n\n**Use Cases:**\n- Identify which stages are slowest\n- See percentage of total time per stage\n- Optimize specific bottlenecks\n\n**Response:**\n- Per-stage metrics (count, avg, p95, max latencies)\n- Total time spent in each stage\n- Percentage of total execution time\n- Sorted by total time (worst bottlenecks first)\n\n**Example:**\n```bash\nGET /v1/analytics/performance/engine/stages?hours=24\n```", "operationId": "get_engine_stage_breakdown_v1_analytics_performance_engine_stages_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 720, "minimum": 1 }, { "type": "null" } ], "description": "Hours of history", "title": "Hours" }, "description": "Hours of history" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date", "title": "Start Date" }, "description": "Start date" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date", "title": "End Date" }, "description": "End date" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EngineStageBreakdownResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/engine/extractors": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Get Extractor Breakdown", "description": "Get extractor performance breakdown.\n\nShows performance metrics for each extractor and its stages.\n\n**Use Cases:**\n- Compare performance across extractors\n- Identify slow extractor stages\n- Monitor specific extractor performance\n\n**Response:**\n- Per-extractor, per-stage metrics\n- Execution counts\n- Latency statistics (avg, p95, max)\n\n**Example:**\n```bash\nGET /v1/analytics/performance/engine/extractors?hours=24\n```", "operationId": "get_extractor_breakdown_v1_analytics_performance_engine_extractors_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 720, "minimum": 1 }, { "type": "null" } ], "description": "Hours of history", "title": "Hours" }, "description": "Hours of history" }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date", "title": "Start Date" }, "description": "Start date" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date", "title": "End Date" }, "description": "End date" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractorBreakdownResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/batches/{batch_id}/diagnostics": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Get Batch Diagnostics", "description": "Get comprehensive diagnostics for a batch.\n\nCombines batch status, task progress, collection info, performance metrics,\nand actionable insights into a single response for easy frontend rendering.\n\n**Use Cases:**\n- Monitor batch processing in real-time\n- Debug failed batches\n- View performance breakdown after completion\n- Get actionable next steps\n\n**Response includes:**\n- Overall batch status and progress\n- Per-tier task details with Ray job links\n- Collection document counts\n- Performance insights and bottlenecks (if completed)\n- Error details (if failed)\n- Recommended next actions\n\n**Example:**\n```bash\nGET /v1/analytics/performance/batches/{batch_id}/diagnostics\n```\n\n**Perfect for:**\n- Real-time progress tracking UI\n- Batch monitoring dashboards\n- Debugging failed extractions\n- Performance optimization", "operationId": "get_batch_diagnostics_v1_analytics_performance_batches__batch_id__diagnostics_get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDiagnostics" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/engine/bottlenecks": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Analyze Bottlenecks", "description": "Identify performance bottlenecks.\n\nAnalyzes profiling data to identify the biggest bottlenecks,\nranked by total time spent.\n\n**Use Cases:**\n- Find what's slowing down your pipelines\n- Prioritize optimization efforts\n- Monitor bottleneck trends\n\n**Ranking:**\n- Sorted by total time spent (sum across all executions)\n- Shows percentage of total execution time\n- Includes execution count and average time\n\n**Example:**\n```bash\nGET /v1/analytics/performance/engine/bottlenecks?hours=24&limit=10\n```", "operationId": "analyze_bottlenecks_v1_analytics_performance_engine_bottlenecks_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 168, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of bottlenecks to return", "default": 10, "title": "Limit" }, "description": "Number of bottlenecks to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BottleneckResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/performance/engine/slow-operations": { "get": { "tags": [ "Analytics", "Analytics - Performance" ], "summary": "Get Slowest Operations", "description": "Get slowest individual operations.\n\nReturns the slowest profiled operations, useful for debugging\nspecific slow executions.\n\n**Use Cases:**\n- Troubleshoot specific slow operations\n- Identify outliers\n- Deep dive into problematic executions\n\n**Filtering:**\n- `threshold_ms`: Only show operations slower than this\n- Default: 1000ms (1 second)\n\n**Response:**\n- Timestamp of slow operation\n- Stage name and component\n- Latency in milliseconds\n- Full metadata context\n\n**Example:**\n```bash\nGET /v1/analytics/performance/engine/slow-operations?hours=24&threshold_ms=5000\n```", "operationId": "get_slowest_operations_v1_analytics_performance_engine_slow_operations_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 168, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Number of operations to return", "default": 10, "title": "Limit" }, "description": "Number of operations to return" }, { "name": "threshold_ms", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "description": "Only show operations slower than this (ms)", "default": 1000.0, "title": "Threshold Ms" }, "description": "Only show operations slower than this (ms)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlowOperationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/usage/summary": { "get": { "tags": [ "Analytics", "Analytics - Usage" ], "summary": "Get Usage Summary", "description": "Get usage summary for billing.\n\nAggregates the organization's usage_records \u2014 the SAME billing source of\ntruth that feeds daily_burn_rate and monthly invoicing (TG-3003: this was\na stub returning ``usage=[]``/``total_cost=0.0``, so Studio's costs view\nshowed $0 while the burn meter recorded millions of credits/day).\n\nReturns per-operation credit totals for the window with USD derived at the\ncanonical $0.001/credit rate (CREDIT_RATE_USD):\n- ``usage``: one row per operation_type \u2014 ``{operation_type, credits,\n cost_usd}`` \u2014 biggest spend first. Refund records are negative and net\n automatically (SP-187).\n- ``total_credits`` / ``total_cost``: window totals across operations.\n\nScoped to the ORGANIZATION (matching the billing meter). Records are only\npartially namespace-attributed (async engine work carries no namespace),\nso filtering by namespace would silently under-report; ``namespace_id`` is\nechoed for request context only.\n\n**Time Range:**\n- If both `start_date` and `end_date` are provided, uses that range\n- If neither provided, defaults to last 30 days\n- If only one provided, defaults to now as the other bound\n\n**Example:**\n```bash\nGET /v1/analytics/usage/summary\nGET /v1/analytics/usage/summary?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z\n```", "operationId": "get_usage_summary_v1_analytics_usage_summary_get", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date (UTC)", "title": "Start Date" }, "description": "Start date (UTC)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date (UTC)", "title": "End Date" }, "description": "End date (UTC)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Usage Summary V1 Analytics Usage Summary Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/extractors/performance": { "get": { "tags": [ "Analytics", "Analytics - Extractors" ], "summary": "Get Extractor Performance", "description": "Get feature extraction performance metrics.\n\nReturns per-extractor execution metrics from the ``extraction_events``\nClickHouse table over the last ``hours`` (namespace-scoped), one row per\n(extractor_name, version):\n- Total executions per extractor\n- Average duration + P95/P99 latencies\n- Success/failure counts and success rate\n\nReturns an empty array when no extraction has run in the window or analytics\nis unavailable.\n\n**Example:**\n```bash\nGET /v1/analytics/extractors/performance?hours=24\nGET /v1/analytics/extractors/performance?extractor_name=text_extractor&hours=168\n```", "operationId": "get_extractor_performance_v1_analytics_extractors_performance_get", "parameters": [ { "name": "extractor_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by extractor", "title": "Extractor Name" }, "description": "Filter by extractor" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Extractor Performance V1 Analytics Extractors Performance Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/inference/performance": { "get": { "tags": [ "Analytics", "Analytics - Inference" ], "summary": "Get Inference Performance", "description": "Get inference performance metrics.\n\nTODO: Implement inference performance query logic.", "operationId": "get_inference_performance_v1_analytics_inference_performance_get", "parameters": [ { "name": "model_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by model", "title": "Model Name" }, "description": "Filter by model" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Inference Performance V1 Analytics Inference Performance Get" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/fields/most-queried": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Most Queried Fields", "description": "Get most frequently queried metadata fields.\n\nIdentifies which metadata fields are accessed most often in retriever queries,\nhelping prioritize index creation and understand query patterns.\n\n**Use Cases:**\n- Identify fields that need indexing\n- Understand common query patterns\n- Prioritize optimization efforts\n- Plan database schema improvements\n\n**Response Includes:**\n- Field name and usage frequency\n- Average and P95 latency metrics\n- Total unique fields analyzed\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/fields/most-queried?days=30&limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_most_queried_fields_v1_analytics_namespaces_fields_most_queried_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum fields to return", "default": 50, "title": "Limit" }, "description": "Maximum fields to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MostQueriedFieldsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/queries/slow": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Slow Queries", "description": "Get slow queries and their filter patterns.\n\nIdentifies queries exceeding a latency threshold and shows which metadata\nfields they're filtering on, helping pinpoint optimization opportunities.\n\n**Use Cases:**\n- Troubleshoot slow queries\n- Identify unindexed fields causing slowdowns\n- Debug performance issues\n- Optimize query patterns\n\n**Response Includes:**\n- Query details (retriever, inputs, latency)\n- Results count\n- Metadata fields being filtered\n- Full query context\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/queries/slow?latency_threshold_ms=1000\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_slow_queries_v1_analytics_namespaces_queries_slow_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "latency_threshold_ms", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10000, "minimum": 100, "description": "Latency threshold in ms", "default": 500, "title": "Latency Threshold Ms" }, "description": "Latency threshold in ms" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Maximum queries to return", "default": 100, "title": "Limit" }, "description": "Maximum queries to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlowQueriesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/fields/performance": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Field Performance", "description": "Analyze field performance correlation.\n\nShows which metadata fields correlate with slow queries, helping identify\nfields that would benefit most from indexing.\n\n**Use Cases:**\n- Identify fields causing performance issues\n- Quantify indexing impact potential\n- Prioritize index creation\n- Monitor field usage patterns\n\n**Response Includes:**\n- Field usage count\n- Latency statistics (avg, P50, P95, P99, max)\n- Index priority score (usage \u00d7 latency)\n- Sorted by priority score\n\n**Index Priority Score:**\nHigher scores indicate fields where indexing would have greatest impact.\nScore = (query count) \u00d7 (average latency)\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/fields/performance?days=30\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_field_performance_v1_analytics_namespaces_fields_performance_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum fields to return", "default": 50, "title": "Limit" }, "description": "Maximum fields to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldPerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/indexes/compound-patterns": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Compound Index Patterns", "description": "Identify compound index opportunities.\n\nFinds metadata fields commonly used together in filters, suggesting\nopportunities for compound (multi-field) indexes.\n\n**Use Cases:**\n- Optimize multi-field queries\n- Create compound indexes\n- Understand query complexity\n- Improve complex filter performance\n\n**Response Includes:**\n- Field combinations used together\n- Frequency of combination usage\n- Average and P95 latency\n- Sorted by combination frequency\n\n**Compound Index Example:**\nIf `brand + status` appears frequently, create:\n```javascript\ndb.documents.createIndex({\"metadata.brand\": 1, \"metadata.status\": 1})\n```\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/indexes/compound-patterns\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_compound_index_patterns_v1_analytics_namespaces_indexes_compound_patterns_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum patterns to return", "default": 50, "title": "Limit" }, "description": "Maximum patterns to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompoundIndexResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/indexes/recommendations": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Index Recommendations", "description": "Get comprehensive MongoDB index recommendations.\n\nAnalyzes query patterns and generates prioritized index recommendations\nwith ready-to-use MongoDB commands.\n\n**Use Cases:**\n- Get actionable index suggestions\n- Prioritize database optimization\n- Copy/paste index creation commands\n- Track optimization opportunities\n\n**Recommendation Levels:**\n- **HIGH PRIORITY**: >100 queries, >300ms avg OR >10 very slow queries\n- **MEDIUM PRIORITY**: >50 queries, >200ms avg OR >20 slow queries\n- **LOW PRIORITY**: >10 queries but acceptable performance\n- **NO ACTION**: Low usage, no optimization needed\n\n**Response Includes:**\n- Prioritized recommendations\n- Usage and latency statistics\n- MongoDB index creation commands\n- Summary by priority level\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/indexes/recommendations\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_index_recommendations_v1_analytics_namespaces_indexes_recommendations_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" }, { "name": "min_usage_count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Minimum queries to consider", "default": 5, "title": "Min Usage Count" }, "description": "Minimum queries to consider" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum recommendations to return", "default": 50, "title": "Limit" }, "description": "Maximum recommendations to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexRecommendationsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/errors": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Namespace Errors", "description": "Batch error/failure counts for every collection & cluster in the namespace.\n\nReturns one entry per resource that has at least one error/failure in the\nwindow, in a single response \u2014 replacing the per-resource\n``/analytics/{collections,clusters}/{id}/failures`` fan-out (the Studio\nMonitoring \"Errors & Health\" N+1, which fired ~13+ calls per visit, most\nreturning zero). Collection errors come from the ClickHouse\n``extraction_events`` warehouse; cluster failures from Mongo\n``clustering_results``. An empty ``collections``/``clusters`` list means that\nresource type is healthy for the window.\n\n**Recommended workflow:** call this once for the aggregate health view, then\ncall the per-resource ``/failures`` endpoint lazily ONLY for the (usually\nfew) resources reporting errors to get the full error-type breakdown.\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/errors?hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_namespace_errors_v1_analytics_namespaces_errors_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history to analyze", "default": 72, "title": "Hours" }, "description": "Hours of history to analyze" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceErrorsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/namespaces/summary": { "get": { "tags": [ "Analytics", "Analytics - Namespaces" ], "summary": "Get Namespace Summary", "description": "Get comprehensive namespace optimization summary.\n\nProvides a complete overview of namespace performance including:\n- Top index recommendations\n- Most queried fields\n- Slowest fields\n- Compound index opportunities\n- Summary statistics\n\n**Use Cases:**\n- Get full optimization picture\n- Regular performance reviews\n- Database health checks\n- Planning optimization work\n\n**Response Includes:**\n- Summary statistics (field counts, priority levels)\n- Top 10 index recommendations\n- Top 10 most queried fields\n- Top 10 slowest fields\n- Top 10 compound index opportunities\n\n**Recommended Workflow:**\n1. Call this endpoint for overview\n2. Use specific endpoints for details\n3. Implement high-priority recommendations\n4. Monitor improvement over time\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/namespaces/summary?days=30\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_namespace_summary_v1_analytics_namespaces_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days of history to analyze", "default": 30, "title": "Days" }, "description": "Days of history to analyze" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/indexes/suggestions": { "get": { "tags": [ "Analytics", "Analytics - Indexes" ], "summary": "Get Index Suggestions", "description": "Get index suggestions based on filter usage patterns.", "operationId": "get_index_suggestions_v1_analytics_indexes_suggestions_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Time window in hours to analyze (max 30 days)", "default": 24, "title": "Hours" }, "description": "Time window in hours to analyze (max 30 days)" }, { "name": "min_count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Minimum query count threshold for suggestions", "default": 100, "title": "Min Count" }, "description": "Minimum query count threshold for suggestions" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexSuggestionsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/indexes/usage": { "get": { "tags": [ "Analytics", "Analytics - Indexes" ], "summary": "Get Field Usage", "description": "Get usage statistics for all filtered fields.", "operationId": "get_field_usage_v1_analytics_indexes_usage_get", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(\\d+h|\\d+d)$", "description": "Time period: Xh (hours) or Xd (days), e.g., 24h, 7d, 30d", "default": "24h", "title": "Period" }, "description": "Time period: Xh (hours) or Xd (days), e.g., 24h, 7d, 30d" }, { "name": "min_count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Minimum query count to include a field", "default": 1, "title": "Min Count" }, "description": "Minimum query count to include a field" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldUsageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/storage": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Bucket Storage", "description": "Get storage growth trends over time.\n\nAnalyzes bucket storage metrics including:\n- Total storage size over time\n- Object count trends\n- Growth rates\n\n**Use Cases:**\n- Monitor storage capacity planning\n- Identify storage growth patterns\n- Track object accumulation\n- Alert on unexpected growth\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/storage?group_by=day\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_bucket_storage_v1_analytics_buckets__bucket_id__storage_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date (UTC)", "title": "Start Date" }, "description": "Start date (UTC)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date (UTC)", "title": "End Date" }, "description": "End date (UTC)" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Time grouping: hour, day, week, month", "default": "day", "title": "Group By" }, "description": "Time grouping: hour, day, week, month" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketStorageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/upload-performance": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Upload Performance", "description": "Get upload performance metrics.\n\nAnalyzes upload operations including:\n- Upload latency (P50, P95, P99)\n- Throughput (MB/s)\n- Error rates\n\n**Use Cases:**\n- Monitor upload performance\n- Identify performance degradations\n- Optimize upload strategies\n- Debug upload issues\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/upload-performance?hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_upload_performance_v1_analytics_buckets__bucket_id__upload_performance_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Time grouping: hour, day", "default": "hour", "title": "Group By" }, "description": "Time grouping: hour, day" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadPerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/sync-performance": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Sync Performance", "description": "Get sync performance metrics.\n\nAnalyzes sync job execution including:\n- Files synced/failed\n- Sync duration and throughput\n- Success rates by provider\n\n**Use Cases:**\n- Monitor sync reliability\n- Compare sync configurations\n- Identify slow syncs\n- Debug sync failures\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/sync-performance?hours=168\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_sync_performance_v1_analytics_buckets__bucket_id__sync_performance_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "sync_config_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by sync config ID", "title": "Sync Config Id" }, "description": "Filter by sync config ID" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history (default: 7 days)", "default": 168, "title": "Hours" }, "description": "Hours of history (default: 7 days)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum sync runs to return", "default": 100, "title": "Limit" }, "description": "Maximum sync runs to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncPerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/health": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Namespace Buckets Health", "description": "Get health for ALL buckets in the namespace in one request.\n\nBatch counterpart of GET /{bucket_id}/health: two grouped analytics\nqueries cover the whole namespace instead of a query fan-out per bucket.\nBuckets with no events in the window are omitted from the response and\nshould be treated as healthy.\n\n**Use Cases:**\n- Monitoring dashboards listing many buckets (replaces the per-bucket\n health call fan-out that scaled linearly with bucket count)\n- Alerting sweeps over all buckets\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/health?hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_namespace_buckets_health_v1_analytics_buckets_health_get", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceBucketsHealthResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/health": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Bucket Health", "description": "Get bucket health monitoring metrics.\n\nAnalyzes bucket health including:\n- Error breakdown by type\n- Sync health per configuration\n- Stuck/failing syncs\n- Overall health status\n\n**Use Cases:**\n- Monitor bucket health\n- Identify failing syncs\n- Debug errors by type\n- Alert on unhealthy buckets\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/health?hours=24\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_bucket_health_v1_analytics_buckets__bucket_id__health_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 24, "title": "Hours" }, "description": "Hours of history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketHealthResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/usage": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Bucket Usage", "description": "Get usage and cost metrics.\n\nAnalyzes bucket usage and costs including:\n- Storage costs (GB-hours)\n- Upload operation costs\n- Sync operation costs\n- Cost breakdown by category\n\n**Use Cases:**\n- Track bucket costs\n- Optimize spending\n- Forecast future costs\n- Cost attribution\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/usage?group_by=day\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_bucket_usage_v1_analytics_buckets__bucket_id__usage_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start date (UTC)", "title": "Start Date" }, "description": "Start date (UTC)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End date (UTC)", "title": "End Date" }, "description": "End date (UTC)" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Time grouping: hour, day, week, month", "default": "day", "title": "Group By" }, "description": "Time grouping: hour, day, week, month" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BucketUsageResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/buckets/{bucket_id}/sync-comparison": { "get": { "tags": [ "Analytics", "Analytics - Buckets" ], "summary": "Get Sync Comparison", "description": "Compare performance across sync configurations.\n\nCompares sync configurations by:\n- Average duration and throughput\n- Success rates\n- Total files and bytes synced\n- Provider performance\n\n**Use Cases:**\n- Compare sync providers (S3 vs GCS)\n- Optimize sync configurations\n- Identify best-performing syncs\n- Benchmark sync strategies\n\n**Example:**\n```bash\ncurl -X GET \"https://api.mixpeek.com/v1/analytics/buckets/bkt_abc123/sync-comparison?hours=168\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-Namespace: your-namespace\"\n```", "operationId": "get_sync_comparison_v1_analytics_buckets__bucket_id__sync_comparison_get", "parameters": [ { "name": "bucket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Bucket Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history (default: 7 days)", "default": 168, "title": "Hours" }, "description": "Hours of history (default: 7 days)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncComparisonResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/collections/{collection_id}/overview": { "get": { "tags": [ "Analytics", "Analytics - Collections" ], "summary": "Get Collection Overview", "description": "Get high-level collection health and status metrics.\n\nProvides collection health including:\n- Total document count and recent growth\n- Processing performance and success rates\n- Active enrichments (taxonomies, clusters)\n\n**Use Cases:**\n- Monitor collection health\n- Quick status check\n- Identify collections needing attention", "operationId": "get_collection_overview_v1_analytics_collections__collection_id__overview_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionOverviewResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/collections/{collection_id}/growth": { "get": { "tags": [ "Analytics", "Analytics - Collections" ], "summary": "Get Document Growth", "description": "Get document growth trends over time.\n\nTracks document additions over time, useful for understanding\nbatch processing patterns and indexing velocity.", "operationId": "get_document_growth_v1_analytics_collections__collection_id__growth_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "hour, day, week, month", "default": "day", "title": "Group By" }, "description": "hour, day, week, month" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrowthMetricsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/collections/{collection_id}/extractors": { "get": { "tags": [ "Analytics", "Analytics - Collections" ], "summary": "Get Extractor Performance", "description": "Get feature extractor performance breakdown.\n\nAnalyzes extractor execution metrics including:\n- Execution counts and success/failure rates\n- Latency percentiles (P95, P99)\n- Total processing time\n\n**Use Cases:**\n- Identify slow extractors for optimization\n- Monitor extraction success rates\n- Understanding processing bottlenecks", "operationId": "get_extractor_performance_v1_analytics_collections__collection_id__extractors_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractorPerformanceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/collections/{collection_id}/latency": { "get": { "tags": [ "Analytics", "Analytics - Collections" ], "summary": "Get Latency Metrics", "description": "Get processing latency distribution.\n\nAnalyzes document processing latency including:\n- Latency percentiles over time\n- Slowest document operations\n- Performance trends", "operationId": "get_latency_metrics_v1_analytics_collections__collection_id__latency_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 24, "title": "Hours" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "default": "hour", "title": "Group By" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatencyResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/collections/{collection_id}/failures": { "get": { "tags": [ "Analytics", "Analytics - Collections" ], "summary": "Get Failure Analysis", "description": "Get failure analysis metrics.\n\nDebug processing failures including:\n- Error distribution by type\n- Recent error messages\n- Failure patterns\n\n**Use Cases:**\n- Debug processing failures\n- Identify common error patterns\n- Track error trends", "operationId": "get_failure_analysis_v1_analytics_collections__collection_id__failures_get", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Collection Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 72, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api__analytics__collections__models__FailureAnalysisResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/clusters/{cluster_id}/execution-history": { "get": { "tags": [ "Analytics", "Analytics - Clusters" ], "summary": "Get Execution History", "description": "Get cluster execution history with metrics.\n\nProvides execution timeline including:\n- Execution duration and document counts\n- Algorithm and cluster counts\n- Success/failure status\n\n**Use Cases:**\n- Monitor clustering performance\n- Track execution patterns\n- Identify execution issues", "operationId": "get_execution_history_v1_analytics_clusters__cluster_id__execution_history_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "description": "Hours of history", "default": 168, "title": "Hours" }, "description": "Hours of history" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionHistoryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/clusters/{cluster_id}/failures": { "get": { "tags": [ "Analytics", "Analytics - Clusters" ], "summary": "Get Failure Analysis", "description": "Get cluster failure analysis.\n\nAnalyzes clustering failures including:\n- Error messages and types\n- Failure timestamps\n- Failure patterns\n\n**Use Cases:**\n- Debug clustering failures\n- Identify common error patterns\n- Monitor cluster health", "operationId": "get_failure_analysis_v1_analytics_clusters__cluster_id__failures_get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 168, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api__analytics__clusters__models__FailureAnalysisResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/taxonomies/{taxonomy_id}/assignments": { "get": { "tags": [ "Analytics", "Analytics - Taxonomies" ], "summary": "Get Assignment Metrics", "description": "Get taxonomy assignment metrics over time.\n\nTracks assignment counts including:\n- Assignment volume over time\n- Average confidence scores\n- Unique labels assigned\n\n**Use Cases:**\n- Monitor taxonomy usage\n- Track assignment trends\n- Identify popular labels", "operationId": "get_assignment_metrics_v1_analytics_taxonomies__taxonomy_id__assignments_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "title": "Group By" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentMetricsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/taxonomies/{taxonomy_id}/confidence": { "get": { "tags": [ "Analytics", "Analytics - Taxonomies" ], "summary": "Get Confidence Distribution", "description": "Get confidence score distribution.\n\nAnalyzes assignment confidence including:\n- Distribution across confidence ranges\n- Low-confidence assignment alerts\n- Average confidence trends\n\n**Use Cases:**\n- Monitor taxonomy quality\n- Identify low-confidence assignments\n- Track confidence improvements", "operationId": "get_confidence_distribution_v1_analytics_taxonomies__taxonomy_id__confidence_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 168, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfidenceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/taxonomies/{taxonomy_id}/labels": { "get": { "tags": [ "Analytics", "Analytics - Taxonomies" ], "summary": "Get Label Distribution", "description": "Get label distribution.\n\nAnalyzes label usage including:\n- Top labels by assignment count\n- Label popularity percentages\n- Confidence by label\n\n**Use Cases:**\n- Understand label usage\n- Identify most common categories\n- Balance taxonomy coverage", "operationId": "get_label_distribution_v1_analytics_taxonomies__taxonomy_id__labels_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 720, "minimum": 1, "default": 168, "title": "Hours" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelDistributionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } }, "/v1/analytics/taxonomies/{taxonomy_id}/enrichments": { "get": { "tags": [ "Analytics", "Analytics - Taxonomies" ], "summary": "Get Enrichment History", "description": "Get enrichment execution history.\n\nTracks enrichment operations including:\n- Enrichment success rates\n- Average latency\n- Volume trends\n\n**Use Cases:**\n- Monitor enrichment performance\n- Track success rates\n- Identify performance issues", "operationId": "get_enrichment_history_v1_analytics_taxonomies__taxonomy_id__enrichments_get", "parameters": [ { "name": "taxonomy_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taxonomy Id" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "title": "Group By" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentHistoryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-mixpeek-namespace-scoped": true, "security": [ { "BearerAuth": [], "NamespaceHeader": [] } ] } } }, "components": { "schemas": { "APIKeyCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Human-friendly key label shown in dashboards." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description", "description": "Optional description explaining the key's purpose." }, "permissions": { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array", "title": "Permissions", "description": "Set of permissions granted to the API key. Defaults to full read/write/delete access. Restrict explicitly when creating scoped keys." }, "scopes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResourceScope-Input" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Optional resource scope restrictions applied to the key." }, "rate_limit_override": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Rate Limit Override", "description": "Per-key requests-per-minute override (defaults to plan limit when absent)." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional UTC timestamp when the key automatically expires." }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id", "description": "End-user identifier for document-level ACL. When set, the key becomes user-scoped and all document reads are automatically filtered to documents the principal has access to. This represents an end-user in your application, NOT an org user." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins", "description": "Optional list of allowed HTTP origins for this API key. When set, browser requests must include a matching Origin header. Supports exact matches and wildcard subdomains (e.g., 'https://*.example.com'). Defense-in-depth: Origin headers can be spoofed from non-browser contexts. Null means no origin restriction.", "examples": [ [ "https://docs.example.com", "https://*.example.com" ] ] } }, "type": "object", "required": [ "name" ], "title": "APIKeyCreateRequest", "description": "Payload for creating a new API key.", "examples": [ { "description": "Service account for ingestion pipeline", "name": "backend-service", "permissions": [ "read", "write" ], "rate_limit_override": 120 }, { "name": "analytics-read", "permissions": [ "read" ], "scopes": [ { "operations": [ "read_data" ], "resource_id": "ns_reporting", "resource_type": "namespace" } ] } ] }, "APIKeyCreateResponse": { "properties": { "key_id": { "type": "string", "title": "Key Id", "description": "Public identifier for the API key." }, "key_hash": { "type": "string", "title": "Key Hash", "description": "SHA-256 hash of the plaintext key." }, "key_prefix": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Key Prefix", "description": "Visible prefix of the API key for user identification (e.g., 'sk_abc123...'). Shows the first 10 characters of the plaintext key to help users identify which key is which in lists, without exposing the full secret. This follows industry best practices from GitHub, Stripe, and AWS. Generated automatically for new keys. Older keys may not have this field.", "examples": [ "sk_abc123...", "sk_xyz789..." ] }, "key_type": { "$ref": "#/components/schemas/APIKeyType", "description": "Type of API key. STANDARD for regular organization keys, MARKETPLACE_SUBSCRIPTION for marketplace subscription access tokens.", "default": "standard" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Id", "description": "Marketplace subscription ID if this is a marketplace subscription key. Only set when key_type is MARKETPLACE_SUBSCRIPTION." }, "is_internal": { "type": "boolean", "title": "Is Internal", "description": "SERVER-VERIFIED internal-actor marker (BACKE-2564). When True, this key belongs to Mixpeek's own operations (e.g. the in-org ops/health probe that must authenticate under a dedicated tenant's internal_id because the single-tenant pod gate fail-closes cross-org auth) and its usage is NOT billed to the org: accrue_mvs_usage skips the accrual and consume_credits skips the direct charge. FAIL CLOSED \u2014 absent/False means BILL. This is the ONLY server-side source a billing skip may key on; never the client-influenced X-Mixpeek-Traffic header or mixpeek-loop-* User-Agent. Set only by an admin provisioning an internal key, never from a create request.", "default": false }, "internal_id": { "type": "string", "title": "Internal Id", "description": "Organization internal identifier." }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization public identifier (denormalized)." }, "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the user who owns the key." }, "name": { "type": "string", "title": "Name", "description": "Human-friendly key label." }, "description": { "type": "string", "title": "Description", "description": "Optional description explaining the key usage.", "default": "" }, "permissions": { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array", "title": "Permissions", "description": "Permissions granted to the key." }, "scopes": { "items": { "$ref": "#/components/schemas/ResourceScope-Output" }, "type": "array", "title": "Scopes", "description": "Resource-level scopes restricting the key." }, "rate_limit_override": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rate Limit Override", "description": "Optional per-key rate limit override in requests per minute." }, "status": { "$ref": "#/components/schemas/KeyStatus", "description": "Lifecycle status of the key (active, revoked, expired).", "default": "active" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "UTC timestamp when the key automatically expires." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "UTC timestamp of the last successful request using the key." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "UTC timestamp when the key was created." }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "User identifier that created the key." }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At", "description": "UTC timestamp when the key was revoked (if applicable)." }, "revoked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked By", "description": "User identifier that revoked the key (if applicable)." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins", "description": "Optional list of allowed HTTP origins for this API key. When set, requests must include an Origin header matching one of these values. Supports exact matches (e.g., 'https://docs.example.com') and wildcard subdomains (e.g., 'https://*.example.com'). Only enforced for browser requests (defense-in-depth, not a security boundary). Null means no origin restriction.", "examples": [ [ "https://docs.example.com", "https://*.example.com" ] ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id", "description": "End-user identifier for document-level ACL (row-level security). When set, this key is user-scoped: all document reads are automatically filtered to documents the principal owns or has been granted access to. This represents an end-user in your application, NOT an org user." }, "key": { "type": "string", "title": "Key" } }, "type": "object", "required": [ "key_hash", "internal_id", "user_id", "name", "key" ], "title": "APIKeyCreateResponse", "description": "API key response including the plaintext secret.", "examples": [ { "created_at": "2025-01-01T00:00:00Z", "created_by": "usr_admin", "description": "Service account for ingestion", "internal_id": "int_x1y2z3", "key_hash": "2c26b46b68ffc68ff99b453c1d304134", "key_id": "key_a1b2c3d4e5f6g7h", "key_prefix": "sk_abc123...", "name": "backend-service", "organization_id": "org_demo123", "permissions": [ "read", "write" ], "scopes": [], "status": "active", "user_id": "usr_a1b2c3d4e5f6g7h" } ] }, "APIKeyModel": { "properties": { "key_id": { "type": "string", "title": "Key Id", "description": "Public identifier for the API key." }, "key_hash": { "type": "string", "title": "Key Hash", "description": "SHA-256 hash of the plaintext key." }, "key_prefix": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Key Prefix", "description": "Visible prefix of the API key for user identification (e.g., 'sk_abc123...'). Shows the first 10 characters of the plaintext key to help users identify which key is which in lists, without exposing the full secret. This follows industry best practices from GitHub, Stripe, and AWS. Generated automatically for new keys. Older keys may not have this field.", "examples": [ "sk_abc123...", "sk_xyz789..." ] }, "key_type": { "$ref": "#/components/schemas/APIKeyType", "description": "Type of API key. STANDARD for regular organization keys, MARKETPLACE_SUBSCRIPTION for marketplace subscription access tokens.", "default": "standard" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Id", "description": "Marketplace subscription ID if this is a marketplace subscription key. Only set when key_type is MARKETPLACE_SUBSCRIPTION." }, "is_internal": { "type": "boolean", "title": "Is Internal", "description": "SERVER-VERIFIED internal-actor marker (BACKE-2564). When True, this key belongs to Mixpeek's own operations (e.g. the in-org ops/health probe that must authenticate under a dedicated tenant's internal_id because the single-tenant pod gate fail-closes cross-org auth) and its usage is NOT billed to the org: accrue_mvs_usage skips the accrual and consume_credits skips the direct charge. FAIL CLOSED \u2014 absent/False means BILL. This is the ONLY server-side source a billing skip may key on; never the client-influenced X-Mixpeek-Traffic header or mixpeek-loop-* User-Agent. Set only by an admin provisioning an internal key, never from a create request.", "default": false }, "internal_id": { "type": "string", "title": "Internal Id", "description": "Organization internal identifier." }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization public identifier (denormalized)." }, "user_id": { "type": "string", "title": "User Id", "description": "Identifier of the user who owns the key." }, "name": { "type": "string", "title": "Name", "description": "Human-friendly key label." }, "description": { "type": "string", "title": "Description", "description": "Optional description explaining the key usage.", "default": "" }, "permissions": { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array", "title": "Permissions", "description": "Permissions granted to the key." }, "scopes": { "items": { "$ref": "#/components/schemas/ResourceScope-Output" }, "type": "array", "title": "Scopes", "description": "Resource-level scopes restricting the key." }, "rate_limit_override": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rate Limit Override", "description": "Optional per-key rate limit override in requests per minute." }, "status": { "$ref": "#/components/schemas/KeyStatus", "description": "Lifecycle status of the key (active, revoked, expired).", "default": "active" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "UTC timestamp when the key automatically expires." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "UTC timestamp of the last successful request using the key." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "UTC timestamp when the key was created." }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "User identifier that created the key." }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At", "description": "UTC timestamp when the key was revoked (if applicable)." }, "revoked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked By", "description": "User identifier that revoked the key (if applicable)." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins", "description": "Optional list of allowed HTTP origins for this API key. When set, requests must include an Origin header matching one of these values. Supports exact matches (e.g., 'https://docs.example.com') and wildcard subdomains (e.g., 'https://*.example.com'). Only enforced for browser requests (defense-in-depth, not a security boundary). Null means no origin restriction.", "examples": [ [ "https://docs.example.com", "https://*.example.com" ] ] }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id", "description": "End-user identifier for document-level ACL (row-level security). When set, this key is user-scoped: all document reads are automatically filtered to documents the principal owns or has been granted access to. This represents an end-user in your application, NOT an org user." } }, "type": "object", "required": [ "key_hash", "internal_id", "user_id", "name" ], "title": "APIKeyModel", "description": "API key document stored in MongoDB.", "examples": [ { "created_at": "2025-01-01T00:00:00Z", "created_by": "usr_admin", "description": "Service account for ingestion", "internal_id": "int_x1y2z3", "key_hash": "2c26b46b68ffc68ff99b453c1d304134", "key_id": "key_a1b2c3d4e5f6g7h", "key_prefix": "sk_abc123...", "name": "backend-service", "organization_id": "org_demo123", "permissions": [ "read", "write" ], "scopes": [], "status": "active", "user_id": "usr_a1b2c3d4e5f6g7h" } ] }, "APIKeyType": { "type": "string", "enum": [ "standard", "marketplace_subscription", "retriever", "user_scoped", "session" ], "title": "APIKeyType", "description": "Type of API key determining its purpose and scope.\n\n- STANDARD: Regular organization API key with standard permissions.\n- MARKETPLACE_SUBSCRIPTION: Special key generated for marketplace subscriptions,\n allowing cross-org access to specific marketplace retrievers.\n- RETRIEVER: Per-retriever API key scoped to execute a specific retriever.\n Only the retriever owner can create these keys. Prefix: ret_sk_\n- SESSION: Short-lived key minted by Studio on each login to back the\n authenticated UI. Hidden from the user-facing key list endpoints." }, "APIKeyUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New key label." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description", "description": "Updated description for the key." }, "permissions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array" }, { "type": "null" } ], "title": "Permissions", "description": "Replace existing permissions with the provided list." }, "scopes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResourceScope-Input" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Replace existing scopes. Use empty list for global access." }, "rate_limit_override": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Rate Limit Override", "description": "Updated per-key rate limit override." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "New expiration timestamp. Use null to remove expiration." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/KeyStatus" }, { "type": "null" } ], "description": "Manually set key status (e.g. revoke)." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins", "description": "Replace the key's allowed HTTP origins. Supports exact matches and wildcard subdomains (e.g., 'https://*.example.com'). Use an empty list to remove the origin restriction.", "examples": [ [ "https://docs.example.com", "https://*.example.com" ] ] } }, "type": "object", "title": "APIKeyUpdateRequest", "description": "Partial update payload for an API key." }, "AccountTier": { "type": "string", "enum": [ "build", "scale", "enterprise", "free", "pro", "team" ], "title": "AccountTier", "description": "Account tier (2026-07 pricing overhaul).\n\nCurrent tiers (CC-required, tier minimum is a billing floor):\n BUILD: $25/mo min \u2014 100K objects/mo (managed) / 1M vectors (MVS)\n SCALE: $250/mo min \u2014 1M objects/mo (managed) / 25M vectors (MVS)\n ENTERPRISE: Custom \u2014 dedicated compute, SLA\n\nLEGACY tiers \u2014 still stored on unmigrated orgs; resolvable until the\nPhase-4 migration completes (do NOT remove before then \u2014 org records in\nMongo carry these strings):\n FREE (\u2192 Build or read-only), PRO (\u2192 Build), TEAM (\u2192 Scale)" }, "ActivityEvent": { "properties": { "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO 8601 timestamp of the event." }, "event_type": { "type": "string", "title": "Event Type", "description": "Type of event (context_transition, weight_shift, etc.)." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "User identifier associated with this event, if any." }, "details": { "additionalProperties": true, "type": "object", "title": "Details", "description": "Additional event-specific details." } }, "type": "object", "required": [ "timestamp", "event_type" ], "title": "ActivityEvent", "description": "A single learned fusion activity event." }, "ActivityResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/ActivityEvent" }, "type": "array", "title": "Events", "description": "List of recent activity events." }, "warning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Warning", "description": "Set when the response contains fallback defaults due to an internal error." }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hint", "description": "Set when learned fusion is NOT configured for this retriever \u2014 the payload is a well-formed empty state and this explains how to enable learning (BACKE-2525)." } }, "type": "object", "required": [ "events" ], "title": "ActivityResponse", "description": "Response containing recent learned fusion activity events." }, "AddCreditsRequest": { "properties": { "credits": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Credits", "description": "Number of credits to add. Must be positive.", "examples": [ 1000, 10000, 100000 ] } }, "type": "object", "required": [ "credits" ], "title": "AddCreditsRequest", "description": "Request to add credits to an organization." }, "AddCreditsResponse": { "properties": { "previous_balance": { "type": "integer", "title": "Previous Balance", "description": "Credit balance before addition" }, "credits_added": { "type": "integer", "title": "Credits Added", "description": "Number of credits added" }, "new_balance": { "type": "integer", "title": "New Balance", "description": "Credit balance after addition" }, "previous_tier": { "$ref": "#/components/schemas/AccountTier", "description": "Account tier before addition" }, "new_tier": { "$ref": "#/components/schemas/AccountTier", "description": "Account tier after addition (may auto-upgrade)" }, "tier_upgraded": { "type": "boolean", "title": "Tier Upgraded", "description": "Whether tier was automatically upgraded" } }, "type": "object", "required": [ "previous_balance", "credits_added", "new_balance", "previous_tier", "new_tier", "tier_upgraded" ], "title": "AddCreditsResponse", "description": "Response after adding credits." }, "AddDomainRequest": { "properties": { "domain": { "type": "string", "title": "Domain", "description": "Customer domain (e.g. 'search.acme.com')" }, "is_primary": { "type": "boolean", "title": "Is Primary", "description": "Set as primary domain", "default": false } }, "type": "object", "required": [ "domain" ], "title": "AddDomainRequest" }, "AddObjectsToBatchRequest": { "properties": { "object_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Object Ids", "description": "A list of object IDs to add to the batch.", "examples": [ [ "object_789", "object_101" ] ] } }, "type": "object", "required": [ "object_ids" ], "title": "AddObjectsToBatchRequest", "description": "The request model for adding objects to an existing batch." }, "AdhocExecuteRequest": { "properties": { "collection_identifiers": { "items": { "type": "string" }, "type": "array", "title": "Collection Identifiers", "description": "Collection identifiers (names or IDs) to query. Can be collection names or IDs. Names are automatically resolved. Can be empty for query-only inference mode (e.g., LLM query analysis without documents). Also accepts 'collection_ids' as an alias for backward compatibility.", "examples": [ [ "my_collection" ], [ "col_abc123", "products" ], [] ] }, "input_schema": { "additionalProperties": { "$ref": "#/components/schemas/RetrieverInputSchemaField-Input", "description": "Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.)" }, "type": "object", "title": "Input Schema", "description": "OPTIONAL. Input schema defining expected inputs. Each key is an input name, value is a RetrieverInputSchemaField. Omit it (or pass {}) for a stages-only execute whose stages carry hardcoded query values \u2014 no dynamic inputs needed.", "examples": [ { "query": { "description": "Search query", "required": true, "type": "text" } }, { "query": { "required": true, "type": "text" }, "top_k": { "required": false, "type": "integer" } } ] }, "stages": { "items": { "$ref": "#/components/schemas/StageConfig-Input" }, "type": "array", "minItems": 1, "title": "Stages", "description": "REQUIRED. Ordered list of stage configurations. At least one stage is required for execution." }, "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs", "description": "OPTIONAL. Input values matching the input_schema. These values are passed to stages for parameterization. Omit it (or pass {}) when the stages carry hardcoded query values.", "examples": [ { "query": "machine learning" }, { "query": "AI trends", "top_k": 50 } ] }, "budget_limits": { "anyOf": [ { "$ref": "#/components/schemas/BudgetLimits" }, { "type": "null" } ], "description": "OPTIONAL. Budget limits for execution." }, "stream": { "type": "boolean", "title": "Stream", "description": "Enable streaming execution to receive real-time stage updates via Server-Sent Events (SSE). NOT REQUIRED - defaults to False for standard execution. \n\nWhen stream=True:\n- Response Content-Type: text/event-stream\n- Events emitted: stage_start, stage_complete, stage_error, execution_complete, execution_error\n- Each event is formatted as: data: {json}\\n\\n\n- StreamStageEvent contains: event_type, execution_id, stage_name, stage_index, total_stages, documents (intermediate), statistics, budget_used\n\n\nWhen to use streaming:\n- Progress tracking for multi-stage pipelines\n- Displaying intermediate results as stages complete\n- Real-time budget and performance monitoring\n- Debugging pipeline execution\n\n\nWhen to skip streaming:\n- Single-stage or fast pipelines (<100ms)\n- No need for intermediate results\n- Minimizing overhead is critical", "default": false, "examples": [ false, true ] } }, "type": "object", "required": [ "stages" ], "title": "AdhocExecuteRequest", "description": "Request to execute a retriever ad-hoc without persistence.\n\nThis combines retriever creation parameters with execution inputs to allow\none-time retrieval without saving the retriever configuration.\n\nUse Cases:\n - One-time queries without polluting retriever registry\n - Testing retriever configurations before persisting\n - Dynamic retrieval with varying stage configurations\n - Temporary search operations\n\nBehavior:\n - Retriever is NOT saved to database\n - Execution history is logged but marked as ad-hoc\n - Response includes X-Execution-Mode: adhoc header\n - execution_metadata.retriever_persisted = False\n\nStreaming Execution (stream=True):\n When streaming is enabled, the response uses Server-Sent Events (SSE) format\n with Content-Type: text/event-stream. Each stage emits events as it executes:\n\n Event Types:\n - stage_start: Emitted when a stage begins execution\n - stage_complete: Emitted when a stage finishes with results\n - stage_error: Emitted if a stage encounters an error\n - execution_complete: Emitted after all stages finish successfully\n - execution_error: Emitted if the entire execution fails\n\n Each event is a StreamStageEvent containing:\n - event_type: The type of event\n - execution_id: Unique execution identifier\n - stage_name: Human-readable stage name\n - stage_index: Zero-based stage position\n - total_stages: Total number of stages\n - documents: Intermediate results (for stage_complete)\n - statistics: Stage metrics (duration_ms, input_count, output_count, etc.)\n - budget_used: Cumulative resource consumption (credits, time, tokens)\n\n Response Headers (streaming):\n - Content-Type: text/event-stream\n - Cache-Control: no-cache\n - Connection: keep-alive\n - X-Execution-Mode: adhoc\n\n Example streaming request:\n ```python\n response = requests.post(\n '/v1/retrievers/execute',\n json={\n 'collection_identifiers': ['my_collection'],\n 'input_schema': {'query': {'type': 'text', 'required': True}},\n 'stages': [...],\n 'inputs': {'query': 'machine learning'},\n 'stream': True\n },\n stream=True\n )\n for line in response.iter_lines():\n if line.startswith(b'data: '):\n event = json.loads(line[6:])\n print(f\"{event['event_type']}: {event.get('stage_name')}\")\n ```\n\nStandard Execution (stream=False, default):\n Returns a single ExecuteRetrieverResponse with final documents,\n pagination, and aggregate statistics after all stages complete.\n\nExamples:\n Simple ad-hoc search:\n {\n \"collection_identifiers\": [\"col_123\"],\n \"input_schema\": {\"query\": {\"type\": \"text\", \"required\": True}},\n \"stages\": [{\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\",\n \"config\": {\n \"stage_id\": \"feature_search\",\n \"parameters\": {\n \"searches\": [{\n \"feature_uri\": \"mixpeek://text_extractor@v1/embedding\",\n \"query\": {\n \"input_mode\": \"text\",\n \"text\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }],\n \"final_top_k\": 10\n }\n }\n }],\n \"inputs\": {\"query\": \"machine learning\"},\n \"stream\": false\n }" }, "AdhocExecutionDetail": { "properties": { "execution_id": { "type": "string", "title": "Execution Id", "description": "Unique execution identifier." }, "execution_mode": { "type": "string", "title": "Execution Mode", "description": "Execution mode ('adhoc')." }, "status": { "type": "string", "title": "Status", "description": "Execution status ('completed', 'failed', etc.)." }, "timestamp": { "title": "Timestamp", "description": "When the execution started (UTC)." }, "duration_ms": { "type": "number", "minimum": 0.0, "title": "Duration Ms", "description": "Total execution duration in milliseconds." }, "credits_used": { "type": "number", "minimum": 0.0, "title": "Credits Used", "description": "Credits consumed during execution." }, "total_processed": { "type": "integer", "minimum": 0.0, "title": "Total Processed", "description": "Total documents processed across all stages." }, "total_returned": { "type": "integer", "minimum": 0.0, "title": "Total Returned", "description": "Number of documents returned in final results." }, "cache_hit_rate": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Cache Hit Rate", "description": "Cache hit rate across stages (0.0-1.0)." }, "query_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query Summary", "description": "Brief summary of the query inputs." }, "stages_completed": { "type": "integer", "minimum": 0.0, "title": "Stages Completed", "description": "Number of stages completed." }, "total_stages": { "type": "integer", "minimum": 0.0, "title": "Total Stages", "description": "Total number of stages in the pipeline." }, "collection_ids": { "items": { "type": "string" }, "type": "array", "title": "Collection Ids", "description": "Collections queried during execution." }, "inputs": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inputs", "description": "Full input data provided for execution." }, "inputs_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inputs Hash", "description": "SHA-1 hash of inputs for deduplication." } }, "type": "object", "required": [ "execution_id", "execution_mode", "status", "timestamp", "duration_ms", "credits_used", "total_processed", "total_returned", "stages_completed", "total_stages" ], "title": "AdhocExecutionDetail", "description": "Detailed information about an ad-hoc retriever execution.\n\nExtends AdhocExecutionSummary with full input data and metadata\nfor comprehensive execution analysis." }, "AdhocExecutionSummary": { "properties": { "execution_id": { "type": "string", "title": "Execution Id", "description": "Unique execution identifier." }, "execution_mode": { "type": "string", "title": "Execution Mode", "description": "Execution mode ('adhoc')." }, "status": { "type": "string", "title": "Status", "description": "Execution status ('completed', 'failed', etc.)." }, "timestamp": { "title": "Timestamp", "description": "When the execution started (UTC)." }, "duration_ms": { "type": "number", "minimum": 0.0, "title": "Duration Ms", "description": "Total execution duration in milliseconds." }, "credits_used": { "type": "number", "minimum": 0.0, "title": "Credits Used", "description": "Credits consumed during execution." }, "total_processed": { "type": "integer", "minimum": 0.0, "title": "Total Processed", "description": "Total documents processed across all stages." }, "total_returned": { "type": "integer", "minimum": 0.0, "title": "Total Returned", "description": "Number of documents returned in final results." }, "cache_hit_rate": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Cache Hit Rate", "description": "Cache hit rate across stages (0.0-1.0)." }, "query_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query Summary", "description": "Brief summary of the query inputs." }, "stages_completed": { "type": "integer", "minimum": 0.0, "title": "Stages Completed", "description": "Number of stages completed." }, "total_stages": { "type": "integer", "minimum": 0.0, "title": "Total Stages", "description": "Total number of stages in the pipeline." }, "collection_ids": { "items": { "type": "string" }, "type": "array", "title": "Collection Ids", "description": "Collections queried during execution." } }, "type": "object", "required": [ "execution_id", "execution_mode", "status", "timestamp", "duration_ms", "credits_used", "total_processed", "total_returned", "stages_completed", "total_stages" ], "title": "AdhocExecutionSummary", "description": "Summary of an ad-hoc retriever execution from ClickHouse.\n\nProvides high-level execution metadata for ad-hoc retrievers without\nfull document results. Used for listing and filtering execution history." }, "AgentConfig": { "properties": { "model": { "type": "string", "title": "Model", "description": "LLM model identifier. Options: 'gemini-2.5-flash-lite' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o'", "default": "gemini-2.5-flash-lite" }, "temperature": { "type": "number", "maximum": 2.0, "minimum": 0.0, "title": "Temperature", "description": "Sampling temperature for LLM responses (0.0-2.0). Lower values (0.0-0.3) are more deterministic. Higher values (0.8-2.0) are more creative.", "default": 0.7 }, "max_tokens": { "type": "integer", "maximum": 100000.0, "minimum": 1.0, "title": "Max Tokens", "description": "Maximum tokens per response", "default": 4096 }, "system_prompt": { "type": "string", "title": "System Prompt", "description": "System prompt that defines agent behavior and persona", "default": "You are a helpful AI assistant with access to Mixpeek's data infrastructure." }, "available_tools": { "items": { "type": "string" }, "type": "array", "title": "Available Tools", "description": "List of API operations the agent is allowed to call. See AvailableTool enum for full list. When provided, the agent's meta-tools will restrict API calls to only these operations. When empty (default), the agent can call any API operation. Key operations: smart_search, execute_retriever, execute_adhoc_retriever, list_collections, list_retrievers, list_buckets, create_upload, analyze_sample_with_pipeline, export_manifest, generate_manifest, detect_intent." } }, "type": "object", "title": "AgentConfig", "description": "Agent configuration for session.\n\nThis config is immutable after session creation (similar to RetrieverConfig).\nTo change agent config, create a new session.\n\nAttributes:\n model: LLM model identifier. Supported models:\n - gemini-2.5-flash (fastest, cheapest)\n - gemini-2.5-pro (better quality)\n - gpt-4o-mini, gpt-4o\n temperature: Sampling temperature for LLM responses (0.0-2.0)\n - 0.0-0.3: More deterministic, focused responses\n - 0.5-0.7: Balanced creativity and coherence\n - 0.8-2.0: More creative, varied responses\n max_tokens: Maximum tokens per response (1-100000)\n system_prompt: System prompt that defines agent behavior and persona\n available_tools: List of tools the agent can call (see AvailableTool enum)\n\nExample:\n ```python\n config = AgentConfig(\n model=\"gemini-2.5-flash-lite\",\n temperature=0.7,\n max_tokens=4096,\n system_prompt=\"You are a helpful video search assistant.\",\n available_tools=[\n \"smart_search\",\n \"execute_retriever\",\n \"list_collections\"\n ]\n )\n ```", "examples": [ { "available_tools": [ "list_retrievers", "get_retriever", "execute_retriever", "list_collections", "get_collection" ], "max_tokens": 4096, "model": "claude-sonnet-4-5-20250929", "system_prompt": "You are a video analysis assistant that helps users find and analyze video content.", "temperature": 0.7 }, { "available_tools": [ "list_retrievers", "execute_retriever" ], "max_tokens": 2048, "model": "claude-3-haiku-20240307", "system_prompt": "You are a quick search assistant. Be concise.", "temperature": 0.3 } ] }, "AgglomerativeParams": { "properties": { "n_clusters": { "anyOf": [ { "type": "integer", "minimum": 2.0 }, { "type": "null" } ], "title": "N Clusters", "description": "Number of clusters to find. Can be None if distance_threshold is not None", "default": 2 }, "affinity": { "type": "string", "title": "Affinity", "description": "Metric used to compute linkage. Can be 'euclidean', 'l1', 'l2', 'manhattan', 'cosine', or 'precomputed'", "default": "euclidean" }, "memory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory", "description": "Path to the caching directory" }, "connectivity": { "anyOf": [ {}, { "type": "null" } ], "title": "Connectivity", "description": "Connectivity matrix. Defines which samples are neighbors" }, "compute_full_tree": { "type": "string", "title": "Compute Full Tree", "description": "Whether to compute the full tree ('auto', True, or False)", "default": "auto" }, "linkage": { "type": "string", "title": "Linkage", "description": "Linkage criterion ('ward', 'complete', 'average', 'single')", "default": "ward" }, "distance_threshold": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Distance Threshold", "description": "The linkage distance threshold above which clusters will not be merged" }, "compute_distances": { "type": "boolean", "title": "Compute Distances", "description": "Whether to compute distances between clusters", "default": false } }, "type": "object", "title": "AgglomerativeParams", "description": "Parameters for Agglomerative clustering algorithm." }, "AggregationFunction": { "type": "string", "enum": [ "count", "count_distinct", "sum", "avg", "min", "max", "first", "last", "push", "add_to_set" ], "title": "AggregationFunction", "description": "Supported aggregation functions.\n\nThese functions can be applied to fields during aggregation operations.\n\nValues:\n COUNT: Count total number of items in each group\n COUNT_DISTINCT: Count unique values in a field\n SUM: Sum numeric values\n AVG: Calculate average of numeric values\n MIN: Find minimum value\n MAX: Find maximum value\n FIRST: Get first value in group\n LAST: Get last value in group\n PUSH: Collect all values into an array\n ADD_TO_SET: Collect unique values into an array\n\nExamples:\n - Use COUNT for total items per category\n - Use COUNT_DISTINCT for unique users per day\n - Use SUM for total revenue\n - Use AVG for average video duration" }, "AggregationOperation": { "properties": { "function": { "$ref": "#/components/schemas/AggregationFunction", "description": "The aggregation function to apply. Different functions require different field types: COUNT: no field required. SUM/AVG: numeric fields only. MIN/MAX: numeric or date fields. COUNT_DISTINCT: any field type." }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field", "description": "The field to aggregate. REQUIRED for all functions except COUNT. NOT REQUIRED for COUNT (counts documents). Supports dot notation for nested fields. Field type must be compatible with function.", "examples": [ "metadata.views", "metadata.duration", "blobs.size", "created_at" ] }, "alias": { "type": "string", "title": "Alias", "description": "Name for the aggregation result in output. REQUIRED for all operations. Should be descriptive of the calculation. Used to reference results in post-filtering.", "examples": [ "total_count", "total_views", "avg_duration", "max_size" ] }, "distinct_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Distinct Field", "description": "Field to count distinct values from. REQUIRED when function is COUNT_DISTINCT. NOT REQUIRED for other functions. Supports dot notation for nested fields.", "examples": [ "metadata.user_id", "metadata.ip_address", "object_id" ] } }, "type": "object", "required": [ "function", "alias" ], "title": "AggregationOperation", "description": "Configuration for an aggregation operation.\n\nDefines a calculation to perform on grouped data.\n\nRequirements:\n - function: REQUIRED, the aggregation function to apply\n - field: REQUIRED for most functions (except COUNT), field to aggregate\n - alias: REQUIRED, name for the result in output\n\nExamples:\n - Count: AggregationOperation(function=\"count\", alias=\"total_count\")\n - Sum: AggregationOperation(function=\"sum\", field=\"metadata.views\", alias=\"total_views\")\n - Average: AggregationOperation(function=\"avg\", field=\"metadata.duration\", alias=\"avg_duration\")", "examples": [ { "alias": "total_count", "description": "Count total documents", "function": "count" }, { "alias": "total_views", "description": "Sum all views", "field": "metadata.views", "function": "sum" }, { "alias": "avg_duration", "description": "Average duration", "field": "metadata.duration", "function": "avg" }, { "alias": "unique_users", "description": "Count unique users", "distinct_field": "metadata.user_id", "function": "count_distinct" } ] }, "AggregationResult": { "properties": { "group": { "additionalProperties": true, "type": "object", "title": "Group", "description": "Grouped field values that define this result row." }, "metrics": { "additionalProperties": true, "type": "object", "title": "Metrics", "description": "Computed aggregation values for this group." } }, "type": "object", "required": [ "group", "metrics" ], "title": "AggregationResult", "description": "Single aggregation result row.\n\nContains grouped field values and computed aggregations.", "examples": [ { "group": { "category": "sports" }, "metrics": { "avg_duration": 245.3, "total_count": 1523 } } ] }, "AlertApplicationConfig-Input": { "properties": { "alert_id": { "type": "string", "title": "Alert Id", "description": "ID of the alert to execute", "examples": [ "alt_safety_001", "alt_content_moderation" ] }, "execution_mode": { "$ref": "#/components/schemas/AlertExecutionMode", "description": "When this alert should execute", "default": "on_ingest" }, "input_mappings": { "items": { "$ref": "#/components/schemas/AlertInputMapping" }, "type": "array", "minItems": 1, "title": "Input Mappings", "description": "Map document fields or constants to retriever input parameters" }, "execution_phase": { "$ref": "#/components/schemas/PostProcessingPhase", "description": "Which phase this alert runs in. Default: ALERT (phase 3, after taxonomies and clusters)", "default": 3 }, "priority": { "type": "integer", "maximum": 1000.0, "minimum": 0.0, "title": "Priority", "description": "Priority within the execution phase (higher = runs first)", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "alert_id", "input_mappings" ], "title": "AlertApplicationConfig", "description": "Configuration for attaching an alert to a collection.\n\nThe key responsibility here is INPUT MAPPING: connecting document\nfields (or constants) to the retriever's expected inputs.\n\nNote: Filtering logic (scroll_filters, min_score, etc.) belongs in\nthe retriever, not here. The retriever owns all query semantics.\n\nUse Cases:\n - Attach safety alert to video upload collection\n - Configure different field mappings for different collections\n - Set execution priority for multiple alerts\n\nAttributes:\n alert_id: ID of the alert to execute\n execution_mode: When this alert should execute\n input_mappings: Map document fields or constants to retriever inputs\n execution_phase: Which phase this alert runs in (default: ALERT)\n priority: Priority within the execution phase (higher = runs first)", "examples": [ { "alert_id": "alt_safety_001", "execution_mode": "on_ingest", "execution_phase": 3, "input_mappings": [ { "input_key": "query_embedding", "source": { "path": "features.video_embedding", "source_type": "document_field" } }, { "input_key": "target_collection", "source": { "source_type": "constant", "value": "col_known_incidents" } } ], "priority": 100 } ] }, "AlertApplicationConfig-Output": { "properties": { "alert_id": { "type": "string", "title": "Alert Id", "description": "ID of the alert to execute", "examples": [ "alt_safety_001", "alt_content_moderation" ] }, "execution_mode": { "$ref": "#/components/schemas/AlertExecutionMode", "description": "When this alert should execute", "default": "on_ingest" }, "input_mappings": { "items": { "$ref": "#/components/schemas/AlertInputMapping" }, "type": "array", "minItems": 1, "title": "Input Mappings", "description": "Map document fields or constants to retriever input parameters" }, "execution_phase": { "$ref": "#/components/schemas/PostProcessingPhase", "description": "Which phase this alert runs in. Default: ALERT (phase 3, after taxonomies and clusters)", "default": 3 }, "priority": { "type": "integer", "maximum": 1000.0, "minimum": 0.0, "title": "Priority", "description": "Priority within the execution phase (higher = runs first)", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "alert_id", "input_mappings" ], "title": "AlertApplicationConfig", "description": "Configuration for attaching an alert to a collection.\n\nThe key responsibility here is INPUT MAPPING: connecting document\nfields (or constants) to the retriever's expected inputs.\n\nNote: Filtering logic (scroll_filters, min_score, etc.) belongs in\nthe retriever, not here. The retriever owns all query semantics.\n\nUse Cases:\n - Attach safety alert to video upload collection\n - Configure different field mappings for different collections\n - Set execution priority for multiple alerts\n\nAttributes:\n alert_id: ID of the alert to execute\n execution_mode: When this alert should execute\n input_mappings: Map document fields or constants to retriever inputs\n execution_phase: Which phase this alert runs in (default: ALERT)\n priority: Priority within the execution phase (higher = runs first)", "examples": [ { "alert_id": "alt_safety_001", "execution_mode": "on_ingest", "execution_phase": 3, "input_mappings": [ { "input_key": "query_embedding", "source": { "path": "features.video_embedding", "source_type": "document_field" } }, { "input_key": "target_collection", "source": { "source_type": "constant", "value": "col_known_incidents" } } ], "priority": 100 } ] }, "AlertExecutionListResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/AlertExecutionResult" }, "type": "array", "title": "Results", "description": "List of execution results" }, "pagination": { "$ref": "#/components/schemas/PaginationResponse", "description": "Pagination information" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of executions" } }, "type": "object", "required": [ "results", "pagination", "total_count" ], "title": "AlertExecutionListResponse", "description": "Response model for listing alert executions." }, "AlertExecutionMode": { "type": "string", "enum": [ "on_ingest", "scheduled", "on_demand" ], "title": "AlertExecutionMode", "description": "When the alert should execute." }, "AlertExecutionResult": { "properties": { "alert_id": { "type": "string", "title": "Alert Id", "description": "ID of the alert that was executed" }, "collection_id": { "type": "string", "title": "Collection Id", "description": "Collection the alert was executed against" }, "execution_id": { "type": "string", "title": "Execution Id", "description": "Unique identifier for this execution" }, "triggered": { "type": "boolean", "title": "Triggered", "description": "Whether the alert was triggered" }, "match_count": { "type": "integer", "minimum": 0.0, "title": "Match Count", "description": "Number of matches found" }, "matches": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AlertMatchResult" }, "type": "array" }, { "type": "null" } ], "title": "Matches", "description": "List of match results" }, "source_documents": { "items": { "type": "string" }, "type": "array", "title": "Source Documents", "description": "Document IDs that triggered the alert check" }, "executed_at": { "type": "string", "title": "Executed At", "description": "ISO 8601 timestamp when the alert was executed" }, "duration_ms": { "type": "integer", "minimum": 0.0, "title": "Duration Ms", "description": "How long the execution took in milliseconds" } }, "type": "object", "required": [ "alert_id", "collection_id", "triggered", "match_count", "executed_at", "duration_ms" ], "title": "AlertExecutionResult", "description": "Result of an alert execution.\n\nCaptures the outcome of running an alert against one or more documents,\nincluding whether the alert was triggered and what matched.\n\nAttributes:\n alert_id: ID of the alert that was executed\n collection_id: Collection the alert was executed against\n execution_id: Unique identifier for this execution\n triggered: Whether the alert was triggered (i.e., retriever returned results)\n match_count: Number of matches found\n matches: List of match results (if include_matches was True)\n source_documents: Document IDs that triggered the alert check\n executed_at: When the alert was executed\n duration_ms: How long the execution took" }, "AlertInputMapping": { "properties": { "input_key": { "type": "string", "title": "Input Key", "description": "The retriever input parameter name", "examples": [ "query_embedding", "collection_id", "category_filter" ] }, "source": { "$ref": "#/components/schemas/InputMappingSource", "description": "Where to get the value from" } }, "type": "object", "required": [ "input_key", "source" ], "title": "AlertInputMapping", "description": "Maps a retriever input to a document field or constant.\n\nInput mappings define how to construct retriever inputs from the\ningested document. This allows the same alert to be used with\ndifferent collections that have different field structures.\n\nExamples:\n # Map document embedding to retriever query\n {\n \"input_key\": \"query_embedding\",\n \"source\": {\"source_type\": \"document_field\", \"path\": \"features.video_embedding\"}\n }\n\n # Use constant collection for search target\n {\n \"input_key\": \"collection_id\",\n \"source\": {\"source_type\": \"constant\", \"value\": \"col_known_incidents\"}\n }\n\nAttributes:\n input_key: The retriever input parameter name\n source: Where to get the value from", "examples": [ { "input_key": "query_embedding", "source": { "path": "features.video_embedding", "source_type": "document_field" } }, { "input_key": "target_collection", "source": { "source_type": "constant", "value": "col_known_incidents" } } ] }, "AlertListStats": { "properties": { "total_alerts": { "type": "integer", "title": "Total Alerts", "description": "Total number of alerts", "default": 0 }, "enabled_alerts": { "type": "integer", "title": "Enabled Alerts", "description": "Number of enabled alerts", "default": 0 }, "disabled_alerts": { "type": "integer", "title": "Disabled Alerts", "description": "Number of disabled alerts", "default": 0 }, "alerts_by_channel_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Alerts By Channel Type", "description": "Count of alerts by notification channel type" } }, "type": "object", "title": "AlertListStats", "description": "Aggregate statistics for a list of alerts." }, "AlertMatchResult": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "ID of the matched document" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id", "description": "Asset ID of the matched document" }, "score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Score", "description": "Similarity/relevance score" }, "matched_features": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Matched Features", "description": "Features that caused the match" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata from the matched document" } }, "type": "object", "required": [ "document_id", "score" ], "title": "AlertMatchResult", "description": "A single match from alert execution.\n\nRepresents a document that matched the retriever's query criteria.\n\nAttributes:\n document_id: ID of the matched document\n asset_id: Asset ID of the matched document\n score: Similarity/relevance score\n matched_features: Optional features that caused the match\n metadata: Optional metadata from the matched document" }, "AlertNotificationConfig": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/NotificationChannelConfig" }, "type": "array", "minItems": 1, "title": "Channels", "description": "List of notification channels to send alerts to" }, "include_matches": { "type": "boolean", "title": "Include Matches", "description": "Include matched documents in notification payload", "default": true }, "include_scores": { "type": "boolean", "title": "Include Scores", "description": "Include similarity scores in notification payload", "default": true }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id", "description": "Optional notification template for formatting" } }, "type": "object", "required": [ "channels" ], "title": "AlertNotificationConfig", "description": "How and where to send notifications when an alert is triggered.\n\nDefines the notification channels and what information to include\nin the notification payload.\n\nAttributes:\n channels: List of channels to send notifications to\n include_matches: Whether to include matched documents in the payload\n include_scores: Whether to include similarity scores in the payload\n template_id: Optional template for formatting the notification", "examples": [ { "channels": [ { "channel_id": "wh_safety_team", "channel_type": "webhook" }, { "channel_id": "sl_alerts", "channel_type": "slack" } ], "include_matches": true, "include_scores": true } ] }, "AlertResponse": { "properties": { "alert_id": { "type": "string", "title": "Alert Id", "description": "Unique identifier for the alert", "examples": [ "alt_abc123xyz789" ] }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace this alert belongs to", "examples": [ "ns_production", "ns_staging" ] }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Human-readable name for the alert", "examples": [ "Safety Incident Detector", "Prohibited Content Alert" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description", "description": "Optional description of what this alert monitors", "examples": [ "Alerts when new videos match known safety incidents" ] }, "source": { "$ref": "#/components/schemas/AlertSource", "description": "Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)", "default": "retriever" }, "retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retriever Id", "description": "ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.", "examples": [ "ret_safety_search", "ret_prohibited_content" ] }, "trigger_on": { "$ref": "#/components/schemas/TriggerOn", "description": "For source=retriever: fire on 'results' (matches found) or 'no_results' (retriever went dark).", "default": "results" }, "system_condition": { "anyOf": [ { "$ref": "#/components/schemas/SystemCondition" }, { "type": "null" } ], "description": "Built-in data-plane condition to watch (source=system only)" }, "namespace_selector": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceSelector" }, { "type": "null" } ], "description": "Org-level namespace scoping (all vs selected). When omitted, the alert is scoped to its own namespace_id." }, "notification_config": { "$ref": "#/components/schemas/AlertNotificationConfig", "description": "How and where to send notifications when alert triggers" }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the alert is active and will execute", "default": true }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp when the alert was created" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Timestamp when the alert was last updated" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional user-defined metadata for the alert" } }, "type": "object", "required": [ "name", "notification_config" ], "title": "AlertResponse", "description": "Response model for a single alert.", "examples": [ { "alert_id": "alt_safety_001", "description": "Alerts when new videos match known safety incidents", "enabled": true, "name": "Safety Incident Detector", "notification_config": { "channels": [ { "channel_id": "wh_safety_team", "channel_type": "webhook" } ], "include_matches": true, "include_scores": true }, "retriever_id": "ret_safety_search" } ] }, "AlertSource": { "type": "string", "enum": [ "retriever", "system" ], "title": "AlertSource", "description": "Where an alert's trigger decision comes from.\n\nSend the lowercase wire value (shown in quotes), NOT the member name.\n\n\"retriever\": runs a retriever against ingested data and fires on (no-)match.\n \"Does my data contain something?\"\n\"system\": evaluates a built-in data-plane metric against a threshold.\n \"Is my pipeline / data healthy?\" No retriever involved." }, "AlignmentMetrics": { "properties": { "ndcg_at_k": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Ndcg At K", "description": "Normalized Discounted Cumulative Gain at various K values." }, "mean_rank_clicked": { "type": "number", "title": "Mean Rank Clicked", "description": "Average position of clicked items in the new ranking." }, "mean_rank_purchased": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Rank Purchased", "description": "Average position of purchased items (if any purchases observed)." }, "recall_at_k": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Recall At K", "description": "Fraction of interacted items found in top K results." }, "avg_position_delta": { "type": "number", "title": "Avg Position Delta", "description": "Average change in position for interacted items (negative = promoted)." }, "items_promoted": { "type": "integer", "minimum": 0.0, "title": "Items Promoted", "description": "Number of interacted items moved to higher positions." }, "items_demoted": { "type": "integer", "minimum": 0.0, "title": "Items Demoted", "description": "Number of interacted items moved to lower positions." }, "sessions_improved": { "type": "integer", "minimum": 0.0, "title": "Sessions Improved", "description": "Sessions where candidate outperformed baseline." }, "sessions_degraded": { "type": "integer", "minimum": 0.0, "title": "Sessions Degraded", "description": "Sessions where candidate underperformed baseline." }, "sessions_neutral": { "type": "integer", "minimum": 0.0, "title": "Sessions Neutral", "description": "Sessions with no significant difference." } }, "type": "object", "required": [ "ndcg_at_k", "mean_rank_clicked", "recall_at_k", "avg_position_delta", "items_promoted", "items_demoted", "sessions_improved", "sessions_degraded", "sessions_neutral" ], "title": "AlignmentMetrics", "description": "Metrics measuring how well a ranking aligns with observed user behavior.\n\nThese metrics compare a candidate pipeline's ranking against ground truth\nderived from actual user interactions (clicks, purchases, etc.).", "examples": [ { "avg_position_delta": -1.5, "items_demoted": 45, "items_promoted": 120, "mean_rank_clicked": 4.2, "mean_rank_purchased": 2.8, "ndcg_at_k": { "5": 0.78, "10": 0.82, "20": 0.85 }, "recall_at_k": { "5": 0.65, "10": 0.8, "20": 0.92 }, "sessions_degraded": 210, "sessions_improved": 580, "sessions_neutral": 210 } ] }, "AnalysisType": { "type": "string", "enum": [ "transitions", "paths" ], "title": "AnalysisType", "description": "Kind of taxonomy step-analytics computed for a persisted run.\n\nAttributes:\n TRANSITIONS: Direct A\u2192B transition analytics (conversion rate, durations,\n predictor lifts) produced by the ``/analytics/transitions`` endpoint.\n PATHS: Multi-step path discovery produced by the ``/analytics/paths``\n endpoint." }, "AnnotationResponse": { "properties": { "annotation_id": { "type": "string", "title": "Annotation Id", "description": "Unique annotation identifier." }, "document_id": { "type": "string", "title": "Document Id", "description": "The document this annotation is attached to." }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id", "description": "Collection the document belongs to." }, "namespace_id": { "type": "string", "title": "Namespace Id", "description": "Namespace scope." }, "label": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Label", "description": "Human decision label. Domain-specific \u2014 e.g. 'approved', 'rejected', 'deferred', 'infringement', 'safe', 'confirmed_dupe'." }, "confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence", "description": "Human confidence in this decision (0.0\u20131.0)." }, "reasoning": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Reasoning", "description": "Why this decision was made. Stored for audit trail." }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload", "description": "Use-case-specific structured data. E.g. {'codes_approved': ['E11.40'], 'raf_impact': 0.302}" }, "retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retriever Id", "description": "Retriever that produced the document being annotated." }, "execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Id", "description": "Retriever execution ID." }, "stage_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage Name", "description": "Stage that produced the result (e.g. 'llm_enrich')." }, "actor_id": { "type": "string", "title": "Actor Id", "description": "Who made the annotation (user ID or API key ID).", "default": "system" }, "actor_type": { "type": "string", "title": "Actor Type", "description": "Actor type: 'user', 'api_key', or 'system'.", "default": "system" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "document_id", "namespace_id", "label" ], "title": "AnnotationResponse", "description": "Single annotation response.", "examples": [ { "actor_id": "user_eric", "actor_type": "user", "annotation_id": "ann_abc123def4567890", "collection_id": "col_notes", "confidence": 0.95, "document_id": "doc_xyz", "label": "approved", "namespace_id": "ns_vitae", "payload": { "codes_approved": [ "E11.40", "E11.65" ], "raf_impact": 0.42 }, "reasoning": "Note clearly documents peripheral neuropathy.", "retriever_id": "ret_hcc_review" } ] }, "AnnotationStatsResponse": { "properties": { "total": { "type": "integer", "title": "Total", "default": 0 }, "by_label": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Label" } }, "type": "object", "title": "AnnotationStatsResponse", "description": "Aggregate stats for annotations." }, "AnthropicModel": { "type": "string", "enum": [ "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001", "claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022" ], "title": "AnthropicModel", "description": "Anthropic Claude model identifiers for LLM generation.\n\nClaude models excel at long context, complex reasoning, and safety.\nAll models support text and images.\n\nValues:\n CLAUDE_3_5_SONNET: Most capable Claude model\n - Use for: Complex reasoning, long documents, safety-critical\n - Context: 200K tokens\n - Vision: Yes\n - Cost: $3/1M input, $15/1M output\n - Performance: 300-800ms per request\n - When to use: Need best reasoning, safety, or long context\n\n CLAUDE_3_5_HAIKU: Fast, cost-effective Claude model\n - Use for: High-volume, quick summaries\n - Context: 200K tokens\n - Vision: Yes\n - Cost: $0.25/1M input, $1.25/1M output\n - Performance: 100-300ms per request\n - When to use: Good balance of quality and cost\n\nExamples:\n - Use CLAUDE_3_5_SONNET for complex entity extraction from contracts (best reasoning)\n - Use CLAUDE_3_5_HAIKU for high-volume content moderation (cost-effective)" }, "AppAnalyticsResponse": { "properties": { "app_id": { "type": "string", "title": "App Id" }, "period_hours": { "type": "integer", "title": "Period Hours" }, "total_errors": { "type": "integer", "title": "Total Errors" }, "error_rate_per_minute": { "type": "number", "title": "Error Rate Per Minute" }, "errors_over_time": { "items": { "$ref": "#/components/schemas/ErrorBucket" }, "type": "array", "title": "Errors Over Time" }, "vitals": { "items": { "$ref": "#/components/schemas/VitalsSummary" }, "type": "array", "title": "Vitals" }, "recent_errors": { "items": { "$ref": "#/components/schemas/RecentError" }, "type": "array", "title": "Recent Errors" }, "total_events": { "type": "integer", "title": "Total Events" }, "total_pageviews": { "type": "integer", "title": "Total Pageviews" } }, "type": "object", "required": [ "app_id", "period_hours", "total_errors", "error_rate_per_minute", "errors_over_time", "vitals", "recent_errors", "total_events", "total_pageviews" ], "title": "AppAnalyticsResponse" }, "AppInvitationResponse": { "properties": { "invitation_id": { "type": "string", "title": "Invitation Id" }, "email_address": { "type": "string", "title": "Email Address" }, "role": { "type": "string", "title": "Role" }, "status": { "type": "string", "title": "Status" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "invitation_id", "email_address", "role", "status" ], "title": "AppInvitationResponse" }, "AppListItem": { "properties": { "app_id": { "type": "string", "title": "App Id" }, "slug": { "type": "string", "title": "Slug" }, "url": { "type": "string", "title": "Url" }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "is_active": { "type": "boolean", "title": "Is Active" }, "version": { "type": "integer", "title": "Version" }, "has_unpublished_changes": { "type": "boolean", "title": "Has Unpublished Changes", "default": false }, "template": { "type": "string", "title": "Template" }, "custom_domains": { "items": { "$ref": "#/components/schemas/CustomDomainConfig" }, "type": "array", "title": "Custom Domains" }, "auth_config": { "anyOf": [ { "$ref": "#/components/schemas/AuthConfig-Output" }, { "type": "null" } ] }, "build_config": { "anyOf": [ { "$ref": "#/components/schemas/BuildConfig" }, { "type": "null" } ] }, "monitoring_config": { "anyOf": [ { "$ref": "#/components/schemas/MonitoringConfig" }, { "type": "null" } ] }, "repo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo Url" }, "repo_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo Branch" }, "environments": { "additionalProperties": true, "type": "object", "title": "Environments" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "app_id", "slug", "url", "meta", "is_active", "version", "template", "custom_domains" ], "title": "AppListItem", "description": "Lightweight app summary for list endpoints.\n\nExcludes heavy fields (sections, custom_html, tabs, versions,\nfeatured_gallery) that can make the full list response 10-30 MB.\nUse GET /apps/{app_id} for the complete record." }, "AppLogsResponse": { "properties": { "app_id": { "type": "string", "title": "App Id" }, "log_type": { "type": "string", "title": "Log Type" }, "results": { "items": {}, "type": "array", "title": "Results", "description": "Log entries \u2014 the platform-standard envelope key (every other list endpoint returns 'results'). Same content as 'entries'." }, "entries": { "items": {}, "type": "array", "title": "Entries", "description": "DEPRECATED alias of 'results', kept for existing consumers. This endpoint predated the platform envelope convention; parse 'results'.", "deprecated": true } }, "type": "object", "required": [ "app_id", "log_type" ], "title": "AppLogsResponse" }, "AppResponse": { "properties": { "app_id": { "type": "string", "title": "App Id" }, "slug": { "type": "string", "title": "Slug" }, "url": { "type": "string", "title": "Url", "description": "Canonical published URL (https://{slug}.mxp.co)" }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "is_active": { "type": "boolean", "title": "Is Active" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "description": "Non-fatal advisories about the request that was just applied. Currently used to spell out the effect of a takedown write, e.g. 'is_active: false' makes the canvas runtime refuse the app's URL with a 404 within its serving-cache window, and the note says how to verify that. Additive and safe to ignore." }, "version": { "type": "integer", "title": "Version" }, "has_unpublished_changes": { "type": "boolean", "title": "Has Unpublished Changes", "default": false }, "custom_domains": { "items": { "$ref": "#/components/schemas/CustomDomainConfig" }, "type": "array", "title": "Custom Domains" }, "auth_config": { "anyOf": [ { "$ref": "#/components/schemas/AuthConfig-Output" }, { "type": "null" } ] }, "build_config": { "anyOf": [ { "$ref": "#/components/schemas/BuildConfig" }, { "type": "null" } ] }, "monitoring_config": { "anyOf": [ { "$ref": "#/components/schemas/MonitoringConfig" }, { "type": "null" } ] }, "repo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo Url" }, "repo_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo Branch" }, "github_installation_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Github Installation Id" }, "versions": { "items": { "$ref": "#/components/schemas/VersionRecord" }, "type": "array", "title": "Versions", "description": "Deploy version history with timestamps and environment info" }, "environments": { "additionalProperties": true, "type": "object", "title": "Environments" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "template": { "type": "string", "title": "Template", "deprecated": true }, "sections": { "items": { "$ref": "#/components/schemas/SectionConfig" }, "type": "array", "title": "Sections", "deprecated": true }, "custom_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Html", "deprecated": true }, "hero": { "anyOf": [ { "$ref": "#/components/schemas/HeroConfig" }, { "type": "null" } ], "deprecated": true }, "theme": { "$ref": "#/components/schemas/ThemeConfig", "deprecated": true }, "seo": { "anyOf": [ { "$ref": "#/components/schemas/SEOConfig" }, { "type": "null" } ], "deprecated": true }, "stats": { "items": { "$ref": "#/components/schemas/StatItem" }, "type": "array", "title": "Stats", "deprecated": true }, "featured_gallery": { "anyOf": [ { "$ref": "#/components/schemas/FeaturedGalleryConfig-Output" }, { "type": "null" } ], "deprecated": true }, "tabs": { "items": { "$ref": "#/components/schemas/PageTab-Output" }, "type": "array", "title": "Tabs", "deprecated": true }, "password_protected": { "type": "boolean", "title": "Password Protected", "deprecated": true } }, "type": "object", "required": [ "app_id", "slug", "url", "meta", "is_active", "version", "custom_domains", "auth_config", "build_config", "environments", "created_at", "updated_at", "template", "sections", "custom_html", "hero", "theme", "seo", "stats", "featured_gallery", "tabs", "password_protected" ], "title": "AppResponse", "description": "Response model for an App.\n\nDeploy-based apps use ``versions``, ``environments``, ``build_config``,\nand ``auth_config``. Legacy page-builder fields (``template``,\n``sections``, ``custom_html``, ``hero``, ``theme``, ``seo``, ``stats``,\n``featured_gallery``, ``tabs``, ``password_protected``) are included\nfor backward compatibility but **deprecated**." }, "AppUserResponse": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "membership_id": { "type": "string", "title": "Membership Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "role": { "type": "string", "title": "Role" }, "joined_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Joined At" } }, "type": "object", "required": [ "user_id", "membership_id", "role" ], "title": "AppUserResponse" }, "ApplyClusterEnrichmentRequest": { "properties": { "clustering_ids": { "items": { "type": "string" }, "type": "array", "title": "Clustering Ids", "description": "Clustering result IDs to apply" }, "source_collection_id": { "type": "string", "title": "Source Collection Id", "description": "Collection to enrich" }, "target_collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Collection Id", "description": "Target collection to write enriched docs to" }, "batch_size": { "type": "integer", "minimum": 1.0, "title": "Batch Size", "description": "Batch size for processing", "default": 1000 }, "parallelism": { "type": "integer", "minimum": 1.0, "title": "Parallelism", "description": "Parallel workers", "default": 1 } }, "type": "object", "required": [ "clustering_ids", "source_collection_id" ], "title": "ApplyClusterEnrichmentRequest", "description": "Request to apply clustering enrichment to a collection.\n\nSupports applying multiple clustering results in one request via\n`clustering_ids`. For backward compatibility, a single `clustering_id`\nis also accepted and up-converted." }, "ApplyPromoRequest": { "properties": { "code": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Code" } }, "type": "object", "required": [ "code" ], "title": "ApplyPromoRequest" }, "ApplyPromoResponse": { "properties": { "applied": { "type": "boolean", "title": "Applied" }, "code": { "type": "string", "title": "Code" }, "percent_off": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percent Off" }, "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount Off Cents" }, "duration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Duration" }, "duration_in_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration In Months" }, "expires_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "applied", "code" ], "title": "ApplyPromoResponse" }, "ApplyResult": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether all resources were created successfully" }, "resources": { "items": { "$ref": "#/components/schemas/ResourceResult" }, "type": "array", "title": "Resources", "description": "Results for each resource" }, "created_count": { "type": "integer", "title": "Created Count", "description": "Number of resources created", "default": 0 }, "failed_count": { "type": "integer", "title": "Failed Count", "description": "Number of resources that failed", "default": 0 }, "skipped_count": { "type": "integer", "title": "Skipped Count", "description": "Number of resources skipped", "default": 0 }, "errors": { "items": { "type": "string" }, "type": "array", "title": "Errors", "description": "Error messages" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "description": "Non-fatal issues found while PARSING the manifest, chiefly keys the parser had to drop. MG-1435: the parser already detects these and /validate and /lint already surface them, but /apply computed them and threw them away \u2014 so anyone applying without validating first got a 201 and no hint that part of their manifest was ignored. A collection-level `field_passthrough:` is the case that cost a customer POC: detected, described, discarded." }, "rollback_performed": { "type": "boolean", "title": "Rollback Performed", "description": "Whether a rollback was ATTEMPTED after a failure. MG-1440: this used to read as 'the namespace was returned to its prior state', which it does not mean \u2014 rollback deletes only namespaces and buckets today, so any other resource created before the failure SURVIVES. Read `rollback_orphans` to find out what is still there.", "default": false }, "rollback_orphans": { "items": { "type": "string" }, "type": "array", "title": "Rollback Orphans", "description": "Resources created before the failure that rollback did NOT delete, as '/'. Non-empty means the namespace is in a PARTIAL state and a straight retry will hit AlreadyExists on these. MG-1440: previously these were silently skipped while rollback_performed=true claimed otherwise, which is the state that had to be unpicked by hand on the Radio-Canada POC." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "Whether this was a dry run (no changes made)", "default": false } }, "type": "object", "required": [ "success" ], "title": "ApplyResult", "description": "Result of applying a manifest.", "examples": [ { "created_count": 2, "dry_run": false, "errors": [], "failed_count": 0, "resources": [ { "name": "video_search", "resource_id": "ns_abc123", "resource_type": "namespace", "status": "created" }, { "name": "raw_videos", "resource_id": "bkt_xyz789", "resource_type": "bucket", "status": "created" } ], "rollback_performed": false, "skipped_count": 0, "success": true } ] }, "ApplyTaxonomyRequest": { "properties": { "taxonomy_id": { "type": "string", "title": "Taxonomy Id", "description": "ID of the taxonomy to apply. REQUIRED. Must be an existing taxonomy (tax_*). The taxonomy must already be in the collection's taxonomy_applications list.", "examples": [ "tax_abc123", "tax_products" ] }, "scroll_filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scroll Filters", "description": "Optional filters to limit which documents are enriched. NOT REQUIRED. If not provided, all documents in the collection will be enriched. Use to process specific subsets (e.g., documents missing enrichment).", "examples": [ { "must": [ { "key": "metadata.category", "match": { "value": "products" } } ] }, null ] }, "batch_size": { "type": "integer", "maximum": 5000.0, "minimum": 100.0, "title": "Batch Size", "description": "Number of documents to process in each parallel batch. NOT REQUIRED. Defaults to 1000. Larger batches = fewer Ray tasks but more memory per task. Smaller batches = more Ray tasks but lower memory per task.", "default": 1000, "examples": [ 1000, 500, 2000 ] }, "parallelism": { "type": "integer", "maximum": 20.0, "minimum": 1.0, "title": "Parallelism", "description": "Number of parallel Ray workers to use for processing. NOT REQUIRED. Defaults to 4. Higher parallelism = faster processing but more cluster resources. Set based on available Ray cluster capacity.", "default": 4, "examples": [ 4, 8, 2 ] } }, "type": "object", "required": [ "taxonomy_id" ], "title": "ApplyTaxonomyRequest", "description": "Request to apply a taxonomy to an existing collection.\n\nThis endpoint triggers retroactive taxonomy materialization on\nall documents in a collection using distributed Ray processing.\n\nUse Cases:\n - Apply taxonomy to documents that were ingested before the taxonomy was created\n - Re-apply taxonomy after taxonomy configuration changes\n - Backfill enrichment data for existing collections\n\nRequirements:\n - taxonomy_id: REQUIRED - Must be an existing, valid taxonomy\n - The taxonomy must already be attached to the collection via taxonomy_applications\n - Documents must exist in the collection", "examples": [ { "description": "Apply taxonomy to all documents", "taxonomy_id": "tax_abc123" }, { "description": "Apply taxonomy to filtered documents", "scroll_filters": { "must": [ { "key": "metadata.processed", "match": { "value": false } } ] }, "taxonomy_id": "tax_products" }, { "batch_size": 500, "description": "Apply with custom batch settings", "parallelism": 8, "taxonomy_id": "tax_categories" } ] }, "ApplyTaxonomyResponse": { "properties": { "task_id": { "type": "string", "title": "Task Id", "description": "ID of the Ray task executing the materialization" }, "status": { "type": "string", "title": "Status", "description": "Status of the materialization task", "examples": [ "submitted", "running", "completed", "failed" ] }, "collection_id": { "type": "string", "title": "Collection Id", "description": "Collection ID where taxonomy is being applied" }, "taxonomy_id": { "type": "string", "title": "Taxonomy Id", "description": "Taxonomy ID being applied" }, "estimated_documents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Documents", "description": "Estimated number of documents to process (if available)" } }, "type": "object", "required": [ "task_id", "status", "collection_id", "taxonomy_id" ], "title": "ApplyTaxonomyResponse", "description": "Response from applying taxonomy to collection.\n\nReturns statistics about the materialization process.", "examples": [ { "collection_id": "col_products", "estimated_documents": 15000, "status": "submitted", "task_id": "ray_task_abc123", "taxonomy_id": "tax_categories" } ] }, "AssignmentMetric": { "properties": { "time_bucket": { "type": "string", "format": "date-time", "title": "Time Bucket" }, "assignment_count": { "type": "integer", "title": "Assignment Count" }, "avg_confidence": { "type": "number", "title": "Avg Confidence" }, "unique_labels": { "type": "integer", "title": "Unique Labels" } }, "type": "object", "required": [ "time_bucket", "assignment_count", "avg_confidence", "unique_labels" ], "title": "AssignmentMetric", "description": "Taxonomy assignment metrics." }, "AssignmentMetricsResponse": { "properties": { "taxonomy_id": { "type": "string", "title": "Taxonomy Id" }, "time_range": { "$ref": "#/components/schemas/api__analytics__taxonomies__models__TimeRange" }, "metrics": { "items": { "$ref": "#/components/schemas/AssignmentMetric" }, "type": "array", "title": "Metrics" }, "summary": { "additionalProperties": true, "type": "object", "title": "Summary" } }, "type": "object", "required": [ "taxonomy_id", "time_range", "metrics" ], "title": "AssignmentMetricsResponse", "description": "Taxonomy assignment metrics response." }, "AttributeBasedConfig": { "properties": { "attributes": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Attributes", "description": "List of attribute field names to use for clustering. Documents will be grouped by unique combinations of these attribute values. Supports dot-notation for nested fields (e.g., 'metadata.category'). Order matters for hierarchical grouping: first attribute is top-level, subsequent are nested.", "examples": [ [ "category" ], [ "category", "brand" ], [ "status", "priority" ], [ "metadata.author", "metadata.topic" ] ] }, "hierarchical_grouping": { "type": "boolean", "title": "Hierarchical Grouping", "description": "Whether to create hierarchical clusters based on attribute order. When True: Creates parent clusters for each unique value of the first attribute, then child clusters for subsequent attributes within each parent. When False: Creates flat clusters for each unique combination of all attributes. Example with ['category', 'brand']: hierarchical=True \u2192 'Electronics' (parent) \u2192 'Apple', 'Samsung' (children). hierarchical=False \u2192 'Electronics_Apple', 'Electronics_Samsung' (flat).", "default": false }, "aggregation_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Aggregation Method", "description": "Method for aggregating attribute values when creating cluster centroids. Options: 'most_frequent' (default), 'first', 'last'. Most use cases should use the default.", "examples": [ "most_frequent", "first", "last" ] } }, "type": "object", "required": [ "attributes" ], "title": "AttributeBasedConfig", "description": "Configuration for attribute-based clustering.\n\nAttribute-based clustering groups documents by metadata attributes (e.g., category, brand, status)\ninstead of vector similarity. This is useful for organizing content by business logic rather than\nsemantic similarity.\n\nExamples:\n - Group products by category and brand\n - Organize orders by status and priority\n - Cluster content by author and topic", "examples": [ { "attributes": [ "category" ], "description": "Simple category clustering", "hierarchical_grouping": false }, { "attributes": [ "category", "brand" ], "description": "Hierarchical category \u2192 brand clustering", "hierarchical_grouping": true }, { "aggregation_method": "most_frequent", "attributes": [ "status", "priority" ], "description": "Order status and priority (flat)", "hierarchical_grouping": false } ] }, "AudioFingerprintExtractorParams": { "properties": { "extractor_type": { "type": "string", "const": "audio_fingerprint_extractor", "title": "Extractor Type", "description": "Discriminator field. Must be 'audio_fingerprint_extractor'.", "default": "audio_fingerprint_extractor" }, "segment_duration_sec": { "type": "number", "maximum": 30.0, "minimum": 1.0, "title": "Segment Duration Sec", "description": "Duration of each audio segment in seconds. 5.0: Recommended for sound mark matching. Shorter segments increase recall but reduce per-segment context.", "default": 5.0 }, "segment_hop_sec": { "type": "number", "maximum": 15.0, "minimum": 0.5, "title": "Segment Hop Sec", "description": "Hop size between segments in seconds. 2.5: 50% overlap (recommended). Set equal to segment_duration_sec for no overlap.", "default": 2.5 }, "sample_rate": { "type": "integer", "title": "Sample Rate", "description": "Target sample rate for audio. 48000: CLAP default (recommended). Audio is resampled to this rate before embedding.", "default": 48000 }, "normalize_embeddings": { "type": "boolean", "title": "Normalize Embeddings", "description": "L2-normalize embeddings to unit vectors (recommended for cosine similarity).", "default": true }, "max_audio_length_sec": { "type": "number", "maximum": 600.0, "minimum": 1.0, "title": "Max Audio Length Sec", "description": "Maximum audio length to process in seconds. 120: Default (2 minutes). Audio beyond this is truncated.", "default": 120.0 } }, "type": "object", "title": "AudioFingerprintExtractorParams", "description": "Parameters for the Audio Fingerprint Extractor.\n\nProcesses audio files (or audio extracted from video) through CLAP\n(Contrastive Language-Audio Pretraining) to produce 512-d embeddings\nsuitable for audio fingerprint matching.\n\nCore Pipeline:\n1. Audio extraction (if video input, via FFmpeg)\n2. Segmentation into fixed-length windows\n3. CLAP embedding (laion/clap-htsat-tiny, 512-d)\n4. L2 normalization\n\nUse Cases:\n - Sound mark detection (IP safety)\n - Audio similarity search\n - Music/jingle identification\n - Audio deduplication", "examples": [ { "description": "Sound mark detection (IP safety)", "extractor_type": "audio_fingerprint_extractor", "normalize_embeddings": true, "sample_rate": 48000, "segment_duration_sec": 5.0, "segment_hop_sec": 2.5 }, { "description": "Music identification (longer segments)", "extractor_type": "audio_fingerprint_extractor", "sample_rate": 48000, "segment_duration_sec": 10.0, "segment_hop_sec": 5.0 } ] }, "AuditAction": { "type": "string", "enum": [ "user_created", "user_updated", "user_deleted", "api_key_created", "api_key_rotated", "api_key_revoked", "api_key_scope_updated", "api_key_internal_flagged", "permission_updated", "storage_connection_created", "storage_connection_updated", "storage_connection_deleted", "storage_connection_tested", "storage_connection_failed", "namespace_created", "namespace_updated", "namespace_deleted", "namespace_accessed", "collection_created", "collection_updated", "collection_deleted", "collection_accessed", "document_deleted", "document_bulk_soft_deleted", "bucket_created", "bucket_updated", "bucket_deleted", "bucket_accessed", "retriever_created", "retriever_updated", "retriever_deleted", "retriever_accessed", "retriever_queried", "cluster_created", "cluster_updated", "cluster_deleted", "cluster_executed", "cluster_accessed", "taxonomy_created", "taxonomy_updated", "taxonomy_deleted", "taxonomy_accessed", "alert_created", "alert_updated", "alert_deleted", "alert_accessed", "alert_triggered", "annotation_created", "annotation_updated", "annotation_deleted", "secret_created", "secret_updated", "secret_deleted", "webhook_created", "webhook_updated", "webhook_deleted" ], "title": "AuditAction", "description": "Canonical audit log actions captured for organization events.\n\nThese events are written to the audit trail for compliance, security monitoring,\nand debugging. Each action includes actor, resource, timestamp, and change details.\n\nUser lifecycle actions:\n - USER_CREATED: New user added to organization\n - USER_UPDATED: User role, status, or metadata modified\n - USER_DELETED: User removed from organization\n\nAPI key lifecycle actions:\n - API_KEY_CREATED: New API key generated\n - API_KEY_ROTATED: Key regenerated (old key revoked, new key issued)\n - API_KEY_REVOKED: Key manually revoked\n - API_KEY_SCOPE_UPDATED: Key permissions or scopes modified\n\nPermission actions:\n - PERMISSION_UPDATED: User or key permissions modified\n\nStorage connection actions:\n - STORAGE_CONNECTION_CREATED: New external storage connection configured\n - STORAGE_CONNECTION_UPDATED: Connection settings or credentials updated\n - STORAGE_CONNECTION_DELETED: Connection permanently removed\n - STORAGE_CONNECTION_TESTED: Connection health check performed\n - STORAGE_CONNECTION_FAILED: Connection health check or sync failed\n\nNamespace actions:\n - NAMESPACE_CREATED: New namespace created\n - NAMESPACE_UPDATED: Namespace configuration modified\n - NAMESPACE_DELETED: Namespace permanently removed\n - NAMESPACE_ACCESSED: Namespace read (when read auditing enabled)\n\nCollection actions:\n - COLLECTION_CREATED: New collection created\n - COLLECTION_UPDATED: Collection configuration modified\n - COLLECTION_DELETED: Collection permanently removed\n - COLLECTION_ACCESSED: Collection read (when read auditing enabled)\n\nDocument actions:\n - DOCUMENT_DELETED: Single document removed by ID\n - DOCUMENT_BULK_SOFT_DELETED: A bulk/batch document delete operation\n ran (explicit IDs or filter mode). ONE event per operation, not\n one per document \u2014 carries the count, the collection_id(s), an\n optional caller-supplied reason, and the actor from request\n context. Before this action existed, a document-level wipe\n (bulk-soft-delete or any other document delete path) was\n invisible to the audit trail entirely (BACKE-3150).\n\nBucket actions:\n - BUCKET_CREATED: New bucket created\n - BUCKET_UPDATED: Bucket configuration modified\n - BUCKET_DELETED: Bucket permanently removed\n - BUCKET_ACCESSED: Bucket read (when read auditing enabled)\n\nRetriever actions:\n - RETRIEVER_CREATED: New retriever pipeline created\n - RETRIEVER_UPDATED: Retriever configuration modified\n - RETRIEVER_DELETED: Retriever permanently removed\n - RETRIEVER_ACCESSED: Retriever read (when read auditing enabled)\n - RETRIEVER_QUERIED: Retriever query executed (when read auditing enabled)\n\nCluster actions:\n - CLUSTER_CREATED: New cluster created\n - CLUSTER_UPDATED: Cluster configuration modified\n - CLUSTER_DELETED: Cluster permanently removed\n - CLUSTER_EXECUTED: Cluster job executed\n - CLUSTER_ACCESSED: Cluster read (when read auditing enabled)\n\nTaxonomy actions:\n - TAXONOMY_CREATED: New taxonomy created\n - TAXONOMY_UPDATED: Taxonomy configuration modified\n - TAXONOMY_DELETED: Taxonomy permanently removed\n - TAXONOMY_ACCESSED: Taxonomy read (when read auditing enabled)" }, "AuditEventListResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/AuditEventResponse" }, "type": "array", "title": "Results", "description": "Audit events" }, "total": { "type": "integer", "title": "Total", "description": "Total count matching filters" }, "skip": { "type": "integer", "title": "Skip", "description": "Number of results skipped" }, "limit": { "type": "integer", "title": "Limit", "description": "Number of results returned" } }, "type": "object", "required": [ "results", "total", "skip", "limit" ], "title": "AuditEventListResponse", "description": "Response for listing audit events." }, "AuditEventResponse": { "properties": { "audit_id": { "type": "string", "title": "Audit Id", "description": "Unique audit event identifier" }, "timestamp": { "title": "Timestamp", "description": "When the event occurred" }, "resource_type": { "type": "string", "title": "Resource Type", "description": "Type of resource affected" }, "resource_id": { "type": "string", "title": "Resource Id", "description": "ID of the affected resource" }, "action": { "type": "string", "title": "Action", "description": "Action performed" }, "actor_id": { "type": "string", "title": "Actor Id", "description": "Who performed the action" }, "actor_type": { "type": "string", "title": "Actor Type", "description": "Type of actor", "default": "user" }, "status": { "type": "string", "title": "Status", "description": "Status of the action", "default": "success" }, "changes": { "title": "Changes", "description": "What changed" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Address", "description": "Request IP address" }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Agent", "description": "Request user agent" }, "actor_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Name", "description": "Resolved actor display name" }, "actor_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Email", "description": "Resolved actor email" }, "actor_key_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Key Name", "description": "API key name used" } }, "type": "object", "required": [ "audit_id", "timestamp", "resource_type", "resource_id", "action", "actor_id" ], "title": "AuditEventResponse", "description": "Single audit event in list response." }, "AuditSettings": { "properties": { "read_auditing_enabled": { "type": "boolean", "title": "Read Auditing Enabled", "description": "When enabled, read operations (GET requests) are logged to the audit trail. This includes resource access like NAMESPACE_ACCESSED, BUCKET_ACCESSED, etc. Disabled by default to reduce audit log volume. Enable for compliance requirements that mandate tracking all resource access.", "default": false } }, "type": "object", "title": "AuditSettings", "description": "Organization audit configuration.\n\nControls audit logging behavior for the organization. Allows enabling\nread access auditing for compliance requirements.", "examples": [ { "read_auditing_enabled": false }, { "read_auditing_enabled": true } ] }, "AuditSettingsUpdateRequest": { "properties": { "read_auditing_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Read Auditing Enabled", "description": "Enable or disable read operation auditing." } }, "type": "object", "title": "AuditSettingsUpdateRequest", "description": "Payload for updating audit settings." }, "AuthConfig-Input": { "properties": { "mode": { "type": "string", "enum": [ "public", "clerk", "password", "api_key", "jwt", "sso_oidc", "sso_saml" ], "title": "Mode", "description": "Authentication mode", "default": "public" }, "clerk_org_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clerk Org Id", "description": "Clerk Organization ID for this app (auto-provisioned)" }, "clerk_allowed_providers": { "items": { "type": "string" }, "type": "array", "title": "Clerk Allowed Providers", "description": "Enabled auth providers: google, github, email" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password", "description": "Plaintext password (write-only \u2014 hashed before storage, never returned in responses)" }, "password_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password Hash", "description": "Bcrypt hash of the password (internal \u2014 never exposed in API responses)" }, "saml_idp_metadata_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Idp Metadata Url" }, "saml_sp_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Sp Entity Id" }, "saml_acs_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Acs Url" }, "oidc_issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Issuer" }, "oidc_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Client Id" }, "oidc_client_secret_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Client Secret Name", "description": "Secrets vault key name (never stored inline)" }, "oidc_scopes": { "items": { "type": "string" }, "type": "array", "title": "Oidc Scopes" }, "jwt_jwks_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Jwks Url" }, "jwt_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Audience" }, "jwt_issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Issuer" }, "api_keys": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Api Keys" } }, "type": "object", "title": "AuthConfig", "description": "End-user authentication configuration for an App.\n\nSupported modes:\n- ``public``: No authentication required (default)\n- ``clerk``: Managed auth via Clerk Organizations \u2014 handles Google, GitHub,\n email/password signup/login. Each canvas app maps to a Clerk Organization.\n Users are synced to canvas_users via Clerk webhooks.\n- ``password``: Simple password gate \u2014 visitors must enter a password to\n access the app. The password is hashed (bcrypt) before storage.\n- ``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``: Advanced modes\n retained for future use." }, "AuthConfig-Output": { "properties": { "mode": { "type": "string", "enum": [ "public", "clerk", "password", "api_key", "jwt", "sso_oidc", "sso_saml" ], "title": "Mode", "description": "Authentication mode", "default": "public" }, "clerk_org_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clerk Org Id", "description": "Clerk Organization ID for this app (auto-provisioned)" }, "clerk_allowed_providers": { "items": { "type": "string" }, "type": "array", "title": "Clerk Allowed Providers", "description": "Enabled auth providers: google, github, email" }, "password_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password Hash", "description": "Bcrypt hash of the password (internal \u2014 never exposed in API responses)" }, "saml_idp_metadata_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Idp Metadata Url" }, "saml_sp_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Sp Entity Id" }, "saml_acs_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Saml Acs Url" }, "oidc_issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Issuer" }, "oidc_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Client Id" }, "oidc_client_secret_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Client Secret Name", "description": "Secrets vault key name (never stored inline)" }, "oidc_scopes": { "items": { "type": "string" }, "type": "array", "title": "Oidc Scopes" }, "jwt_jwks_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Jwks Url" }, "jwt_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Audience" }, "jwt_issuer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jwt Issuer" }, "api_keys": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Api Keys" } }, "type": "object", "title": "AuthConfig", "description": "End-user authentication configuration for an App.\n\nSupported modes:\n- ``public``: No authentication required (default)\n- ``clerk``: Managed auth via Clerk Organizations \u2014 handles Google, GitHub,\n email/password signup/login. Each canvas app maps to a Clerk Organization.\n Users are synced to canvas_users via Clerk webhooks.\n- ``password``: Simple password gate \u2014 visitors must enter a password to\n access the app. The password is hashed (bcrypt) before storage.\n- ``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``: Advanced modes\n retained for future use." }, "AutoBillingToggleResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether the operation was successful", "default": true }, "auto_billing_enabled": { "type": "boolean", "title": "Auto Billing Enabled", "description": "New auto-billing status" }, "message": { "type": "string", "title": "Message", "description": "Human-readable message" }, "billing_period_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Billing Period Start", "description": "Billing period start (if enabled)" } }, "type": "object", "required": [ "auto_billing_enabled", "message" ], "title": "AutoBillingToggleResponse", "description": "Response after toggling auto-billing." }, "AvailableOrgModelItem": { "properties": { "model_id": { "type": "string", "title": "Model Id" }, "name": { "type": "string", "title": "Name" }, "version": { "type": "string", "title": "Version" }, "model_format": { "type": "string", "title": "Model Format" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework" }, "task_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Type" }, "enabled_in_namespace": { "type": "boolean", "title": "Enabled In Namespace", "description": "Whether already enabled in the target namespace" } }, "type": "object", "required": [ "model_id", "name", "version", "model_format", "enabled_in_namespace" ], "title": "AvailableOrgModelItem", "description": "Available org model item." }, "AvailableOrgModelsResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "models": { "items": { "$ref": "#/components/schemas/AvailableOrgModelItem" }, "type": "array", "title": "Models" }, "total": { "type": "integer", "title": "Total" }, "namespace_id": { "type": "string", "title": "Namespace Id" } }, "type": "object", "required": [ "models", "total", "namespace_id" ], "title": "AvailableOrgModelsResponse", "description": "Response for listing available org models." }, "AvailableStepsResponse": { "properties": { "taxonomy_id": { "type": "string", "title": "Taxonomy Id", "description": "Taxonomy ID" }, "collection_id": { "type": "string", "title": "Collection Id", "description": "Collection ID" }, "total_events": { "type": "integer", "minimum": 0.0, "title": "Total Events", "description": "Total events in dataset" }, "total_sequences": { "type": "integer", "minimum": 0.0, "title": "Total Sequences", "description": "Total unique sequences" }, "steps": { "items": { "$ref": "#/components/schemas/StepInfo" }, "type": "array", "title": "Steps", "description": "Available steps sorted by count" } }, "type": "object", "required": [ "taxonomy_id", "collection_id", "total_events", "total_sequences", "steps" ], "title": "AvailableStepsResponse", "description": "Response containing all available steps for a taxonomy/collection.\n\nThis endpoint helps users discover what steps exist in their analytics data\nbefore querying transitions or paths.\n\nExample Response:\n ```json\n {\n \"taxonomy_id\": \"tax_sales_stages\",\n \"collection_id\": \"col_emails\",\n \"total_events\": 5432,\n \"total_sequences\": 1000,\n \"steps\": [\n {\n \"step_key\": \"inquiry\",\n \"event_count\": 1000,\n \"sequence_count\": 1000,\n \"first_seen\": \"2025-11-01T00:00:00Z\",\n \"last_seen\": \"2025-12-07T00:00:00Z\"\n },\n {\n \"step_key\": \"followup\",\n \"event_count\": 450,\n \"sequence_count\": 450,\n \"first_seen\": \"2025-11-02T00:00:00Z\",\n \"last_seen\": \"2025-12-06T00:00:00Z\"\n },\n {\n \"step_key\": \"closed_won\",\n \"event_count\": 350,\n \"sequence_count\": 350,\n \"first_seen\": \"2025-11-05T00:00:00Z\",\n \"last_seen\": \"2025-12-07T00:00:00Z\"\n }\n ]\n }\n ```" }, "BYODocument": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Unique document identifier. Upserting with an existing ID replaces the document." }, "vectors": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "type": "object", "title": "Vectors", "description": "Named vectors as a map of vector_name -> embedding values. Example: {\"text-embedding\": [0.1, 0.2, ...], \"image-embedding\": [0.3, ...]}" }, "payload": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "Arbitrary JSON payload stored alongside the vectors." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Document metadata stored in _internal.metadata. Filterable via attribute queries." } }, "type": "object", "required": [ "document_id", "vectors" ], "title": "BYODocument", "description": "A single document with user-provided vectors and payload." }, "BYOUpsertRequest": { "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id", "description": "Target collection. Documents are tagged with this collection_id so they appear in collection-scoped queries, list, and clustering. When omitted a namespace-level default collection is used." }, "documents": { "items": { "$ref": "#/components/schemas/BYODocument" }, "type": "array", "maxItems": 1000, "title": "Documents", "description": "Documents to upsert. Maximum 1000 per call." }, "options": { "anyOf": [ { "$ref": "#/components/schemas/UpsertOptions" }, { "type": "null" } ], "description": "Optional upsert behavior flags." } }, "type": "object", "required": [ "documents" ], "title": "BYOUpsertRequest", "description": "Request body for BYO document upsert." }, "BYOUpsertResponse": { "properties": { "inserted": { "type": "integer", "title": "Inserted", "description": "Number of documents upserted." }, "document_ids": { "items": { "type": "string" }, "type": "array", "title": "Document Ids", "description": "IDs of all upserted documents." }, "write_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Write Token", "description": "Opaque token for read-your-writes consistency (only when requested)." }, "consistency": { "$ref": "#/components/schemas/WriteConsistency", "description": "How and when this write becomes visible to retriever reads." } }, "type": "object", "required": [ "inserted", "document_ids" ], "title": "BYOUpsertResponse", "description": "Response from a BYO document upsert." }, "BackblazeConfig": { "properties": { "provider_type": { "type": "string", "const": "backblaze", "title": "Provider Type", "default": "backblaze" }, "credentials": { "$ref": "#/components/schemas/BackblazeCredentials", "description": "REQUIRED. Backblaze B2 application key credentials." } }, "type": "object", "required": [ "credentials" ], "title": "BackblazeConfig", "description": "Backblaze B2 Cloud Storage configuration.\n\nBackblaze B2 is an S3-compatible object storage service. This provider\nauto-discovers the regional S3 endpoint via the B2 authorization API,\nso users only need to provide their key ID and application key.\n\nAuthentication:\n - Application key ID + application key from Backblaze console\n\nRequirements:\n - Active Backblaze account with B2 Cloud Storage enabled\n - Application key with listBuckets, listFiles, and readFiles capabilities\n - (Optional) Restrict key to specific bucket for scoped access\n\nUse Cases:\n - Cold storage archive ingestion\n - Media file sync from Backblaze-hosted assets\n - Backup data processing\n - Cost-effective large-file storage sync", "examples": [ { "credentials": { "application_key": "K005xxxxxxxxxxxxxxxxxxxxxxxxxxxx", "key_id": "005870eff85b6c60000000001", "type": "application_key" }, "description": "Backblaze B2 bucket sync", "provider_type": "backblaze" } ] }, "BackblazeCredentials": { "properties": { "type": { "type": "string", "const": "application_key", "title": "Type", "default": "application_key" }, "key_id": { "type": "string", "title": "Key Id", "description": "REQUIRED. Backblaze B2 application key ID. Found in: Backblaze Console > App Keys > keyID column.", "examples": [ "005870eff85b6c60000000001" ] }, "application_key": { "type": "string", "title": "Application Key", "description": "REQUIRED. Backblaze B2 application key (secret). SECURITY: Encrypted at rest. Shown only once when key is created. Found in: Backblaze Console > App Keys \u2014 copy immediately on creation.", "examples": [ "K005xxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] } }, "type": "object", "required": [ "key_id", "application_key" ], "title": "BackblazeCredentials", "description": "Application key credentials for Backblaze B2 Cloud Storage.\n\nSecurity:\n - application_key is encrypted at rest via CSFLE\n - Keys can be created/rotated in the Backblaze console" }, "BaseFeatureExtractorModel-Input": { "properties": { "feature_extractor_name": { "type": "string", "title": "Feature Extractor Name", "description": "Name of the feature extractor" }, "version": { "type": "string", "title": "Version", "description": "Version of the feature extractor (e.g., 'v1', 'v2')" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Params", "description": "Optional extractor parameters that affect vector index configuration. Parameters set here are locked at namespace creation and determine vector dimensions in Qdrant. Collections using this extractor must use compatible params. Example: {'model': 'siglip_base'}" } }, "type": "object", "required": [ "feature_extractor_name", "version" ], "title": "BaseFeatureExtractorModel", "description": "Minimum feature extractor definition." }, "BaseFeatureExtractorModel-Output": { "properties": { "feature_extractor_name": { "type": "string", "title": "Feature Extractor Name", "description": "Name of the feature extractor" }, "version": { "type": "string", "title": "Version", "description": "Version of the feature extractor (e.g., 'v1', 'v2')" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Params", "description": "Optional extractor parameters that affect vector index configuration. Parameters set here are locked at namespace creation and determine vector dimensions in Qdrant. Collections using this extractor must use compatible params. Example: {'model': 'siglip_base'}" }, "feature_extractor_id": { "type": "string", "title": "Feature Extractor Id", "description": "Construct unique identifier for the feature extractor instance (name + version).", "readOnly": true } }, "type": "object", "required": [ "feature_extractor_name", "version", "feature_extractor_id" ], "title": "BaseFeatureExtractorModel", "description": "Minimum feature extractor definition." }, "BaseRateLimits": { "properties": { "metadata": { "type": "integer", "minimum": 1.0, "title": "Metadata", "description": "REQUIRED. Rate limit for infrastructure and configuration operations (namespaces, collections, retrievers, taxonomies, clusters CRUD). These are zero-credit operations with highest rate limits since they're cheap to execute. Examples: creating collections, updating retrievers, listing namespaces.", "default": 10, "examples": [ 20, 100, 200 ] }, "data": { "type": "integer", "minimum": 1.0, "title": "Data", "description": "REQUIRED. Rate limit for data operations (objects, documents CRUD). Low-credit operations with high rate limits. Examples: creating documents, updating objects, batch document updates.", "default": 10, "examples": [ 10, 60, 100 ] }, "search": { "type": "integer", "minimum": 1.0, "title": "Search", "description": "REQUIRED. Rate limit for search and retrieval operations (retriever/taxonomy execution). Medium-credit operations with moderate rate limits. Examples: executing retrievers, running taxonomy matching.", "default": 10, "examples": [ 10, 60, 100 ] }, "upload": { "type": "integer", "minimum": 1.0, "title": "Upload", "description": "REQUIRED. Rate limit for file upload operations. Credit-intensive (1 credit/MB) with lower rate limits to prevent excessive resource consumption. Examples: uploading files, generating presigned URLs.", "default": 10, "examples": [ 5, 30, 50 ] }, "compute": { "type": "integer", "minimum": 1.0, "title": "Compute", "description": "REQUIRED. Rate limit for compute operations (cluster execution, batch processing). High-credit operations (10 credits/min video) with lowest rate limits. Examples: submitting batches, executing clusters, triggering syncs.", "default": 10, "examples": [ 5, 30, 50 ] } }, "type": "object", "title": "BaseRateLimits", "description": "Rate limits by operation type (requests per minute).\n\nThe rate limiting system uses 5 categories aligned with actual resource consumption:\n\nCategories:\n metadata: Infrastructure and configuration operations (namespaces, collections,\n retrievers, taxonomies, clusters CRUD). Zero-credit operations with\n highest rate limits.\n\n data: Data operations (objects, documents CRUD). Low-credit operations with\n high rate limits.\n\n search: Search and retrieval operations (retriever/taxonomy execution).\n Medium-credit operations with moderate rate limits.\n\n upload: File upload operations (credit-intensive: 1 credit/MB). Variable-credit\n operations with lower rate limits.\n\n compute: Compute operations (cluster execution, batch processing). High-credit\n operations (10 credits/min video) with lowest rate limits.\n\nRate Limit Strategy:\n Higher limits for low-cost operations (metadata, data)\n Lower limits for high-cost operations (upload, compute)\n This aligns API throttling with actual infrastructure costs\n\nExamples:\n - Creating a namespace: Uses 'metadata' category (fast, cheap)\n - Uploading a file: Uses 'upload' category (slow, expensive per MB)\n - Executing a retriever: Uses 'search' category (moderate cost)\n - Running batch processing: Uses 'compute' category (very expensive)" }, "BaseTemplateModel": { "properties": { "template_id": { "type": "string", "pattern": "^tmpl_[a-z0-9_]+$", "title": "Template Id", "description": "Unique template identifier (e.g., 'tmpl_semantic_search')" }, "template_type": { "$ref": "#/components/schemas/TemplateType", "description": "Type of resource this template creates" }, "mode": { "$ref": "#/components/schemas/TemplateMode", "description": "Template instantiation mode: clone (with data), config (empty), or scaffold (preset)", "default": "config" }, "scope": { "$ref": "#/components/schemas/TemplateScope", "description": "Template scope (system or organization)" }, "internal_id": { "type": "string", "title": "Internal Id", "description": "Organization internal ID. For system templates, use 'system'. For org templates, use the actual internal_id." }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Human-readable template name" }, "description": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Description", "description": "Detailed description of the template's purpose" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Optional category for organizing templates" }, "configuration": { "additionalProperties": true, "type": "object", "title": "Configuration", "description": "Template-specific configuration (varies by template_type)" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "Tags for categorizing and filtering templates" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether this template is available for use", "default": true }, "is_public": { "type": "boolean", "title": "Is Public", "description": "Whether this template is publicly discoverable without authentication", "default": false }, "use_cases": { "items": { "type": "string" }, "type": "array", "title": "Use Cases", "description": "List of common use cases for this template" }, "requirements": { "items": { "type": "string" }, "type": "array", "title": "Requirements", "description": "List of requirements (e.g., 'Requires text embeddings')" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "User ID who created this template (for org templates)" }, "source_resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Resource Id", "description": "ID of the resource this template was created from (for org templates)" }, "sample_namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sample Namespace Id", "description": "Reference to a sample/golden namespace for this scaffold (used for Studio quickstart cloning)" }, "example_queries": { "items": { "type": "string" }, "type": "array", "title": "Example Queries", "description": "Runnable example queries for this template's sample data; the first renders on the card" }, "whats_inside": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Whats Inside", "description": "One-sentence description of the sample corpus (what you get, with counts)" }, "materialize_estimate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Materialize Estimate", "description": "Honest time estimate for sample data to become searchable after instantiate" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when template was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when template was last updated" } }, "type": "object", "required": [ "template_id", "template_type", "scope", "internal_id", "name", "description", "configuration" ], "title": "BaseTemplateModel", "description": "Base template model with common fields for all template types.\n\nThis model is stored in MongoDB and supports three template scopes:\n- System: Mixpeek defaults (all orgs)\n- Organization: All users in the org\n- User: Only the creator", "examples": [ { "category": "semantic_search", "configuration": { "input_schema": {}, "stages": [] }, "created_at": "2025-01-15T12:00:00Z", "description": "Simple text-based semantic search", "internal_id": "system", "is_active": true, "is_public": true, "name": "Basic Semantic Search", "scope": "system", "template_id": "tmpl_semantic_search", "template_type": "retriever" } ] }, "BatchChunkStats": { "properties": { "unit": { "type": "string", "title": "Unit", "description": "Realized unit the chunker grouped by: characters, words, sentences, paragraphs, pages, seconds (time_segments), or none (no chunking; one chunk per input row)." }, "total_chunks": { "type": "integer", "title": "Total Chunks", "description": "Total chunks produced across all processed rows.", "default": 0 }, "mean_units_per_chunk": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Units Per Chunk", "description": "Mean realized chunk size, measured in `unit`. A value near 1 for a count unit (sentences/paragraphs/pages) with a larger configured chunk_size means the configuration is not taking effect as intended." } }, "type": "object", "required": [ "unit" ], "title": "BatchChunkStats", "description": "Realized chunking statistics reported by the text chunker (MHC-250).\n\nSurfaces what chunking ACTUALLY did, measured in the split strategy's\nown unit, so an inert or unit-confused chunking config (for example a\nchunk_size chosen in the wrong unit) is visible by reading the batch\ninstead of forensically diffing two configs' outputs." }, "BatchConfirmRequest": { "properties": { "confirmations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Confirmations", "description": "List of confirmations with upload_id, etag, file_size_bytes" } }, "type": "object", "required": [ "confirmations" ], "title": "BatchConfirmRequest", "description": "Request to confirm multiple uploads in batch.", "examples": [ { "confirmations": [ { "etag": "d41d8cd98f00b204e9800998ecf8427e", "file_size_bytes": 10485760, "upload_id": "upl_abc123" }, { "etag": "7f9c12ab56f4e12d80cf8d98fe12c4a9", "file_size_bytes": 5242880, "upload_id": "upl_def456" } ] } ] }, "BatchConfirmResponse": { "properties": { "task_id": { "type": "string", "title": "Task Id", "description": "Task ID for tracking batch confirmation progress" }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "Task status" }, "confirmations_count": { "type": "integer", "title": "Confirmations Count", "description": "Number of confirmations being processed" }, "task": { "$ref": "#/components/schemas/TaskResponse", "description": "Full task details" }, "message": { "type": "string", "title": "Message", "description": "Status message", "default": "Batch confirmation is being processed in the background." } }, "type": "object", "required": [ "task_id", "status", "confirmations_count", "task" ], "title": "BatchConfirmResponse", "description": "Response from batch confirmation." }, "BatchCost": { "properties": { "credits_consumed": { "type": "integer", "minimum": 0.0, "title": "Credits Consumed", "description": "Total credits recorded against this batch in usage_records (resource_type='batch'). 0 if no usage has been recorded yet (e.g. DRAFT batches, ENTERPRISE tiers that skip credit consumption, or batches submitted before metering existed).", "default": 0, "examples": [ 0, 100, 4820 ] }, "cost_usd": { "type": "number", "minimum": 0.0, "title": "Cost Usd", "description": "Derived dollar cost = credits_consumed * $0.001/credit (CREDIT_RATE_USD). Same rate used by monthly invoicing, so this matches what the batch contributes to the bill.", "default": 0.0, "examples": [ 0.0, 0.1, 4.82 ] }, "credit_rate_usd": { "type": "number", "title": "Credit Rate Usd", "description": "USD per credit used to derive cost_usd ($0.001/credit).", "default": 0.001 } }, "type": "object", "title": "BatchCost", "description": "Dollar cost of a batch, derived from recorded credit usage.\n\nMixpeek meters work in *credits* (recorded in the usage_records\ncollection at credit-consume time, keyed by ``resource_id=batch_id`` /\n``resource_type=\"batch\"``). There is no separately-stored per-batch USD\nfigure, so cost is derived at read time as\n``credits_consumed * CREDIT_RATE_USD`` using the same canonical\n$0.001/credit rate the billing/invoicing path uses. This lets callers\nanswer \"what did this batch cost?\" from the batch GET response without\nGCP billing labels or a separate billing query." }, "BatchCostEstimate": { "properties": { "batch_id": { "type": "string", "title": "Batch Id" }, "collection_ids": { "items": { "type": "string" }, "type": "array", "title": "Collection Ids" }, "dedup_strategy": { "type": "string", "title": "Dedup Strategy", "description": "skip | replace | force \u2014 controls re-extraction", "default": "skip" }, "object_count": { "type": "integer", "title": "Object Count", "description": "Objects this batch will process", "default": 0 }, "already_extracted_count": { "type": "integer", "title": "Already Extracted Count", "description": "Objects in this batch already extracted before (re-paid under force/replace)", "default": 0 }, "estimated_credits": { "type": "integer", "title": "Estimated Credits", "description": "Credits submitting this batch will consume (same calc as submit)", "default": 0 }, "estimated_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Estimated Usd", "description": "Dollar cost of this batch under live v2 pricing (file type \u00d7 amount \u00d7 search-by features). Credits are milli-dollars of this value." }, "estimated_repay_credits": { "type": "integer", "title": "Estimated Repay Credits", "description": "~credits re-paying already-extracted objects (force/replace only; linear approx)", "default": 0 }, "features": { "items": { "type": "string" }, "type": "array", "title": "Features", "description": "What this batch searches by (dimension 3 of pricing): feature keys billed per file type; custom plugins as 'custom:'." }, "extractors": { "items": { "type": "string" }, "type": "array", "title": "Extractors", "description": "Internal implementation of `features` \u2014 prefer rendering `features`; extractor names are the deeper disclosure layer." }, "content_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content Summary", "description": "Dimensions 1+2 of pricing: file types and how much of each (counts, video minutes, pages, tokens\u2026)" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings" } }, "type": "object", "required": [ "batch_id" ], "title": "BatchCostEstimate", "description": "Dry-run estimate of what submitting a DRAFT batch will cost + re-pay." }, "BatchDeleteDocumentsRequest": { "properties": { "document_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "minItems": 1 }, { "type": "null" } ], "title": "Document Ids", "description": "OPTIONAL. List of document IDs to delete. Use this mode when you know exact document IDs to delete. Mutually exclusive with filters mode. Maximum 1000 documents per batch request.", "examples": [ [ "doc_123", "doc_456", "doc_789" ], [ "doc_frame_001", "doc_frame_002" ] ] }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "OPTIONAL. Filter conditions to match documents for deletion. Mutually exclusive with 'document_ids' array. If provided, deletes ALL documents matching the filters. Use with caution - can delete many documents at once. Uses the logical AND/OR/NOT shape (not MVS-native must/key).", "examples": [ { "AND": [ { "field": "metadata.status", "operator": "eq", "value": "archived" } ] } ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Reason", "description": "OPTIONAL. Why this bulk delete is happening \u2014 recorded on the DOCUMENT_BULK_SOFT_DELETED audit event (BACKE-3150) so a document-level wipe carries the caller's own context, not just the actor and counts.", "examples": [ "retention policy cleanup", "customer-requested erasure" ] } }, "type": "object", "title": "BatchDeleteDocumentsRequest", "description": "Request model for batch deleting multiple documents by explicit IDs or filters.\n\nSupports TWO modes:\n1. Explicit IDs mode: Provide 'document_ids' array\n2. Filter mode: Provide 'filters' to delete all matching documents\n\nUse Cases:\n - Delete 5 specific documents in one API call\n - Delete all documents matching criteria\n - Bulk cleanup operations\n\nRequirements:\n - EITHER 'document_ids' OR 'filters' must be provided\n - NOT BOTH modes simultaneously", "examples": [ { "description": "Explicit IDs mode: Delete 3 specific documents", "document_ids": [ "doc_123", "doc_456", "doc_789" ] }, { "description": "Filter mode: Delete all archived documents", "filters": { "AND": [ { "field": "metadata.status", "operator": "eq", "value": "archived" } ] } } ] }, "BatchDeleteDocumentsResponse": { "properties": { "deleted_count": { "type": "integer", "title": "Deleted Count", "description": "Total number of documents successfully deleted" }, "failed_count": { "type": "integer", "title": "Failed Count", "description": "Total number of documents that failed to delete", "default": 0 }, "results": { "items": { "$ref": "#/components/schemas/BatchDocumentDeleteResult" }, "type": "array", "title": "Results", "description": "Detailed per-document results. Each entry shows document_id, success status, and error message (if failed). Empty list when using filter mode (only counts returned)." }, "message": { "type": "string", "title": "Message", "description": "Summary message of the operation", "default": "Batch delete completed" } }, "type": "object", "required": [ "deleted_count" ], "title": "BatchDeleteDocumentsResponse", "description": "Response model for batch document delete operation.\n\nProvides detailed per-document results showing success/failure for each deletion.", "examples": [ { "deleted_count": 3, "failed_count": 0, "message": "Successfully deleted 3 document(s)", "results": [ { "document_id": "doc_123", "success": true }, { "document_id": "doc_456", "success": true }, { "document_id": "doc_789", "success": true } ] } ] }, "BatchDiagnostics": { "properties": { "batch_id": { "type": "string", "title": "Batch Id", "description": "Batch ID" }, "batch_name": { "type": "string", "title": "Batch Name", "description": "Batch name" }, "status": { "type": "string", "title": "Status", "description": "Overall batch status" }, "bucket_id": { "type": "string", "title": "Bucket Id", "description": "Source bucket ID" }, "current_tier": { "type": "integer", "title": "Current Tier", "description": "Current tier being processed", "default": 0 }, "total_tiers": { "type": "integer", "title": "Total Tiers", "description": "Total number of tiers", "default": 1 }, "overall_progress": { "type": "number", "title": "Overall Progress", "description": "Overall progress percentage (0-100)", "default": 0.0 }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "When batch was created" }, "submitted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Submitted At", "description": "When batch was submitted" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When processing started" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When processing completed" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Total duration in seconds" }, "estimated_completion": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Estimated Completion", "description": "Estimated completion time" }, "tiers": { "items": { "$ref": "#/components/schemas/TierDiagnostic" }, "type": "array", "title": "Tiers", "description": "Diagnostic info for each tier" }, "collections": { "items": { "$ref": "#/components/schemas/CollectionDiagnostic" }, "type": "array", "title": "Collections", "description": "Status of target collections" }, "performance_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Performance Summary", "description": "Performance metrics summary (available after completion)" }, "insights": { "items": { "$ref": "#/components/schemas/PerformanceInsight" }, "type": "array", "title": "Insights", "description": "Performance insights and recommendations" }, "has_failures": { "type": "boolean", "title": "Has Failures", "description": "Whether batch has any failures", "default": false }, "failed_tier_count": { "type": "integer", "title": "Failed Tier Count", "description": "Number of failed tiers", "default": 0 }, "health": { "type": "string", "title": "Health", "description": "Derived health signal: 'ok', 'scaling' (PROCESSING with no progress yet but still inside the GPU cold-start / cluster-provisioning window \u2014 a scale-from-zero node and image pull can take ~20 min, so this is expected, not stuck), 'stuck' (PROCESSING but no progress and the active tier's job has been PENDING past the cold-start window \u2014 its driver/worker may be unschedulable), or 'degraded' (has partial failures).", "default": "ok" }, "blocked_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Blocked Reason", "description": "Human-readable reason the batch appears stuck/blocked, or \u2014 for health='scaling' \u2014 why it is legitimately waiting (e.g. 'cluster_cold_start: GPU workers scaling from zero'). None when health is 'ok' or 'degraded'." }, "stuck_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Stuck Seconds", "description": "How long the batch has been making no progress while PROCESSING, in seconds. None when not stuck." }, "total_objects": { "type": "integer", "title": "Total Objects", "description": "Total objects in batch", "default": 0 }, "next_actions": { "items": { "type": "string" }, "type": "array", "title": "Next Actions", "description": "Recommended next steps for user" } }, "type": "object", "required": [ "batch_id", "batch_name", "status", "bucket_id" ], "title": "BatchDiagnostics", "description": "Comprehensive batch diagnostics response.\n\nCombines batch status, task progress, collection info, and performance\ninsights into a single response for easy frontend rendering." }, "BatchDocumentDeleteResult": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Document ID that was deleted" }, "success": { "type": "boolean", "title": "Success", "description": "Whether the deletion succeeded" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if deletion failed" } }, "type": "object", "required": [ "document_id", "success" ], "title": "BatchDocumentDeleteResult", "description": "Result of a single document deletion in a batch operation." }, "BatchDocumentUpdate": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "REQUIRED. Document ID to update. Must exist in the collection. Format: 'doc_' prefix + alphanumeric characters.", "examples": [ "doc_abc123", "doc_frame_001" ] }, "update_data": { "additionalProperties": true, "type": "object", "title": "Update Data", "description": "REQUIRED. Fields to update for this specific document. Can update any document field except vectors. Supported fields: metadata, source_blobs, document_blobs, lineage fields (root_object_id, source_type, etc.), and any custom fields. Each document in the batch can have different update_data.", "examples": [ { "metadata": { "score": 0.95, "status": "processed" } }, { "metadata": { "reviewed": true, "reviewer": "John" } } ] } }, "type": "object", "required": [ "document_id", "update_data" ], "title": "BatchDocumentUpdate", "description": "Single document update specification for batch operations.\n\nRepresents one document's update within a batch request.", "examples": [ { "document_id": "doc_abc123", "update_data": { "metadata": { "status": "processed" } } } ] }, "BatchDocumentUpdateResult": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Document ID that was updated" }, "success": { "type": "boolean", "title": "Success", "description": "Whether the update succeeded" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if update failed" } }, "type": "object", "required": [ "document_id", "success" ], "title": "BatchDocumentUpdateResult", "description": "Result of a single document update in a batch operation." }, "BatchErrorDetail": { "properties": { "error_type": { "$ref": "#/components/schemas/ErrorCategory", "description": "REQUIRED. Category of error that occurred. Used for filtering, retry logic, and error analytics. DEPENDENCY: Missing packages/modules (e.g., google-genai not installed). AUTHENTICATION: Invalid credentials or expired tokens. VALIDATION: Schema mismatches or invalid input data. RUNTIME: Code exceptions or processing failures. NETWORK: Connectivity issues or timeouts. RESOURCE: Out of memory or disk space.", "examples": [ "dependency", "authentication", "validation" ] }, "message": { "type": "string", "title": "Message", "description": "REQUIRED. Human-readable error message. Concise description of what went wrong. Should be actionable and help users understand the issue.", "examples": [ "Missing required package: google-genai", "Invalid API key for Vertex AI", "Schema validation failed: missing required field 'products'" ] }, "component": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Component", "description": "OPTIONAL. Component or service where the error occurred. Helps identify which part of the system failed. Examples: service class names, module names, or feature names.", "examples": [ "VertexMultimodalService", "WhisperTranscriptionService", "GeminiExtractor" ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage", "description": "OPTIONAL. Processing stage where the error occurred. Identifies which pipeline stage failed. Examples: pipeline stage names from collection configuration.", "examples": [ "gemini_extraction", "whisper_transcription", "embedding_generation" ] }, "traceback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Traceback", "description": "OPTIONAL. Full Python traceback for debugging. Includes stack trace for code-level troubleshooting. Should be truncated if too long (e.g., max 2000 chars)." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "REQUIRED. ISO 8601 timestamp when the error occurred. Used for chronological error tracking and debugging.", "examples": [ "2025-11-29T10:15:30Z" ] }, "affected_document_ids": { "items": { "type": "string" }, "type": "array", "title": "Affected Document Ids", "description": "OPTIONAL. List of document IDs affected by this error. For object-level errors: contains single document ID. For batch-level aggregation: contains all affected document IDs. Used to identify scope of impact.", "examples": [ [ "doc_123" ], [ "doc_123", "doc_456", "doc_789" ] ] }, "affected_count": { "type": "integer", "minimum": 1.0, "title": "Affected Count", "description": "REQUIRED. Number of documents affected by this error. For object-level: typically 1. For batch-level aggregation: total count of affected documents. Used for error impact analysis.", "default": 1, "examples": [ 1, 10, 50 ] }, "recovery_suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recovery Suggestion", "description": "OPTIONAL. Actionable suggestion for resolving the error. Helps users quickly fix common issues. Examples: install missing package, check credentials, update schema.", "examples": [ "Install google-genai package: pip install google-genai", "Verify your Vertex AI credentials are configured correctly", "Update your schema to include required 'products' field" ] }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "OPTIONAL. Additional error context and metadata. Free-form dictionary for error-specific details. Examples: retry_count, last_retry_at, error_code, http_status.", "examples": [ { "last_retry_at": "2025-11-29T10:10:00Z", "retry_count": 2 }, { "api_endpoint": "https://vertex.googleapis.com", "http_status": 401 } ] } }, "type": "object", "required": [ "error_type", "message" ], "title": "BatchErrorDetail", "description": "Detailed error information for batch processing failures.\n\nProvides structured error tracking at both object and batch levels.\nEnables better debugging, retry logic, and error analytics.\n\nUse Cases:\n - Track specific errors that occurred during processing\n - Identify error patterns across multiple documents\n - Provide actionable recovery suggestions\n - Enable intelligent retry logic based on error type\n\nObject-level tracking: Attached to individual document processing failures\nBatch-level tracking: Aggregated summaries in batch metadata", "examples": [ { "affected_count": 1, "affected_document_ids": [ "doc_123" ], "component": "VertexMultimodalService", "description": "Dependency error: Missing package", "error_type": "dependency", "message": "Cannot import 'genai' from 'google' package", "metadata": { "import_path": "google.genai", "package_name": "google-genai" }, "recovery_suggestion": "Install google-genai package: pip install google-genai", "stage": "gemini_extraction", "timestamp": "2025-11-29T10:15:30Z", "traceback": "ImportError: cannot import name 'genai' from 'google'..." }, { "affected_count": 2, "affected_document_ids": [ "doc_456", "doc_789" ], "component": "VertexMultimodalService", "description": "Authentication error: Invalid credentials", "error_type": "authentication", "message": "Invalid grant: Bad Request", "metadata": { "http_status": 401, "retry_count": 3 }, "recovery_suggestion": "Verify your Vertex AI service account credentials", "stage": "gemini_extraction", "timestamp": "2025-11-29T10:20:00Z" } ] }, "BatchGetDocumentsRequest": { "properties": { "document_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "minItems": 1, "title": "Document Ids", "description": "List of document IDs to retrieve." }, "return_presigned_urls": { "type": "boolean", "title": "Return Presigned Urls", "description": "Generate presigned download URLs for document blobs.", "default": false } }, "type": "object", "required": [ "document_ids" ], "title": "BatchGetDocumentsRequest", "description": "Batch retrieve documents by their IDs." }, "BatchGetDocumentsResponse": { "properties": { "documents": { "items": { "$ref": "#/components/schemas/DocumentResponse" }, "type": "array", "title": "Documents", "description": "Retrieved documents." }, "not_found": { "items": { "type": "string" }, "type": "array", "title": "Not Found", "description": "Document IDs that were not found." } }, "type": "object", "title": "BatchGetDocumentsResponse", "description": "Response for batch document retrieval." }, "BatchListDocumentsRequest": { "properties": { "queries": { "items": { "$ref": "#/components/schemas/BatchListQuery" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Queries", "description": "Queries to execute concurrently against the same namespace." } }, "type": "object", "required": [ "queries" ], "title": "BatchListDocumentsRequest", "description": "Batch-execute multiple namespace-scoped list-documents queries in parallel.\n\nIntended to collapse dossier / multi-collection UI N+1 patterns into one\nround-trip. Canvas pages that fan out 5\u201310 parallel `list_documents`\ncalls (e.g., scene counts + face clusters + scene archetypes filtered by\nthe same brand_slug) should bundle them here instead." }, "BatchListDocumentsResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BatchListResult" }, "type": "array", "title": "Results", "description": "One entry per input query, in the same order as requested." } }, "type": "object", "required": [ "results" ], "title": "BatchListDocumentsResponse", "description": "Response for `POST /v1/documents/list/batch`." }, "BatchListQuery": { "properties": { "key": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Key", "description": "Client-supplied identifier echoed back in the response. Use anything unique within the batch (e.g., 'scenes', 'face_clusters')." }, "request": { "$ref": "#/components/schemas/NamespaceListDocumentsRequest", "description": "List-documents request body, identical to POST /v1/documents/list." } }, "type": "object", "required": [ "key", "request" ], "title": "BatchListQuery", "description": "A single list-documents query within a batch-list request.\n\nEach query carries a client-supplied `key` used to correlate the result\nback to the caller, plus a full `NamespaceListDocumentsRequest` body \u2014\nthe same shape accepted by `POST /v1/documents/list`." }, "BatchListResult": { "properties": { "key": { "type": "string", "title": "Key", "description": "The client-supplied key from the request." }, "response": { "anyOf": [ { "$ref": "#/components/schemas/ListDocumentsResponse" }, { "type": "null" } ], "description": "List response on success; None when `error` is populated." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Short human-readable error message if this sub-query failed. Per-query failures do not fail the whole batch." } }, "type": "object", "required": [ "key" ], "title": "BatchListResult", "description": "Single query result within a batch-list response." }, "BatchMetadata": { "properties": { "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Id", "description": "Identifier linking this batch to a marketing or processing campaign.", "examples": [ "Q4_2025", "onboarding_wave_3" ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Origin of the batch data (e.g. an S3 prefix, partner name, or pipeline stage).", "examples": [ "s3://raw-uploads/2026-05/", "partner_acme" ] }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Free-form tags for filtering and grouping batches.", "examples": [ [ "video", "high-priority" ], [ "backfill", "Q2" ] ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes", "description": "Free-form notes about this batch (intent, context, special handling).", "examples": [ "Re-run after Whisper quota fix", "TubeScience daily ingest" ] } }, "additionalProperties": true, "type": "object", "title": "BatchMetadata", "description": "Typed user-defined metadata for a batch.\n\nKnown fields are validated and surfaced in API docs. Additional\narbitrary keys are accepted via ``model_config extra=\"allow\"``." }, "BatchModel": { "properties": { "batch_id": { "type": "string", "title": "Batch Id", "description": "OPTIONAL (auto-generated if not provided). Unique identifier for this batch. Format: 'btch_' prefix followed by 12-character secure token. Generated using generate_secure_token() from shared.utilities.helpers. Used to query batch status and track processing across tiers. Immutable after creation.", "examples": [ "btch_abc123xyz789", "btch_video_batch_01" ] }, "bucket_id": { "type": "string", "title": "Bucket Id", "description": "REQUIRED. Unique identifier of the bucket containing the objects to process. Must be a valid bucket ID that exists in the system. All object_ids must belong to this bucket. Format: Bucket ID as defined when bucket was created.", "examples": [ "bkt_videos", "bkt_documents_q4" ] }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace this batch belongs to. Stored at creation time." }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "OPTIONAL (defaults to DRAFT). Current processing status of the batch. Lifecycle: DRAFT \u2192 PENDING \u2192 IN_PROGRESS \u2192 COMPLETED/FAILED. DRAFT: Batch created but not yet submitted. PENDING: Batch submitted and queued for processing. IN_PROGRESS: Batch currently processing (one or more tiers active). COMPLETED: All tiers successfully completed. FAILED: One or more tiers failed. Aggregated from tier_tasks statuses during multi-tier processing.", "default": "DRAFT", "examples": [ "DRAFT", "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, "queue_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Queue Context", "description": "Populated on GET while the batch is PENDING/PROCESSING: how many earlier active batches are ahead in this namespace's queue and how long this batch has been waiting, so an in-flight status is never opaque." }, "object_ids": { "items": { "type": "string" }, "type": "array", "minItems": 0, "title": "Object Ids", "description": "List of object IDs to include in this batch. All objects must exist in the specified bucket_id. These objects are the source data for tier 0 processing. Collection-sourced batches may have empty object_ids. Objects are processed in parallel within each tier.", "examples": [ [ "obj_video_001", "obj_video_002" ], [ "obj_doc_123" ] ] }, "dedup_strategy": { "$ref": "#/components/schemas/DedupStrategy", "description": "Controls how objects already processed in prior batches are handled. Scoped to (bucket, collection). 'skip': Don't reprocess objects that already have documents. 'replace': Delete existing documents and reprocess. 'force': Process regardless, allowing duplicates.", "default": "skip" }, "submitted_by_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Submitted By Key Id", "description": "key_id of the API key that submitted this batch, resolved server-side at creation. None for async/system-created batches with no request actor context. Audit only." }, "submitted_by_key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Submitted By Key Prefix", "description": "Display prefix of the submitting API key. Audit only." }, "submitted_by_is_internal": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Submitted By Is Internal", "description": "Whether the submitting key was server-verified internal AT SUBMIT TIME. None = no actor context (unattributable); never used for billing decisions (those read the live key marker)." }, "dedup_audit": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Dedup Audit", "description": "Per-collection dedup decisions. Keys are collection_ids; values contain dedup_strategy, total_input, skipped, processed, and skipped_object_ids (up to 1000). Written at TWO stages, deep-merged per collection: (1) the API at manifest build, when smart-skip enforcement excludes already-complete objects before any engine submission (fields prefixed manifest_*), and (2) the Engine after its resume filter runs on whatever residue was submitted." }, "collection_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Collection Ids", "description": "OPTIONAL. List of all collection IDs involved in this batch's processing. Automatically populated during DAG resolution from dag_tiers. Includes collections from all tiers (flattened view of dag_tiers). Used for quick lookups without traversing tier structure. Format: List of collection IDs across all tiers.", "examples": [ [ "col_chunks" ], [ "col_chunks", "col_frames", "col_scenes" ] ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "OPTIONAL. Legacy error message field for backward compatibility. None if batch succeeded or is still processing. Contains human-readable error description from first failed tier. DEPRECATED: Use tier_tasks[].errors for detailed error information. For multi-tier batches, typically contains the error from the first failed tier. Check tier_tasks array for tier-specific error details and error_summary for aggregation.", "examples": [ "Failed to process batch: Object not found", "Tier 1 failed: Out of memory during frame extraction", "Collection 'col_frames' not found" ] }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason", "description": "OPTIONAL. Human-readable explanation of why the batch failed. None if batch succeeded, is still processing, or is in DRAFT/PENDING state. Populated automatically when a batch transitions to FAILED status. Provides a concise, actionable summary of the root cause. Common reasons include: Ray job failure (spot preemption, OOM, code errors), 0 documents written (processing completed but produced no output), processing stall (no activity detected for extended period), or task exception (submission/validation failures). Use this field for user-facing error displays and alerting.", "examples": [ "Ray job failed: ImportError: No module named 'google.genai'", "Processing completed but produced 0 documents. Check Ray job logs for '[FailureAggregator]' entries.", "Processing stalled: no activity for 30 minutes. Job was cancelled automatically.", "Namespace ns_abc123 no longer exists (may have been deleted)." ] }, "error_summary": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Error Summary", "description": "OPTIONAL. Aggregated summary of errors across ALL tiers in the batch. Maps error_type (category) to total count of affected DOCUMENTS across all tiers. None has THREE causes, not two: the batch succeeded, it is still processing, OR a tier FAILED AT TIER LEVEL and wrote zero documents, so no individual document carries an error and this histogram is legitimately empty. So None does NOT mean 'no errors', and None alongside COMPLETED_WITH_ERRORS is NOT a contradiction \u2014 read `failure_reason` and `tier_tasks[].error` for tier-level diagnosis. Provides quick batch-wide overview of error distribution. Example: {'dependency': 15, 'authentication': 25, 'validation': 5} means across all tiers, 15 documents failed with dependency errors, 25 with auth errors, 5 with validation errors. Automatically aggregated from tier_tasks[].error_summary. Used for batch health dashboard and error trend analysis.", "examples": [ null, { "dependency": 15 }, { "authentication": 25, "runtime": 10, "validation": 5 } ] }, "failure_category": { "anyOf": [ { "$ref": "#/components/schemas/FailureCategory" }, { "type": "null" } ], "description": "OPTIONAL. Machine-readable classification of the batch failure. None if batch succeeded or is still processing. Auto-derived from `failure_reason` if not explicitly set, so existing writers that only populate `failure_reason` still get a category on read. Categories: timeout (stall/no-progress), infrastructure (OOM, workers died, spot preemption), orphaned (RayJob CRD gone), pipeline (genuine extractor/pipeline failure), validation (submission/schema errors), unknown (uncategorized). Use this instead of parsing failure_reason.", "examples": [ null, "timeout", "infrastructure", "pipeline" ] }, "failed_objects": { "items": { "$ref": "#/components/schemas/FailedObjectRecord" }, "type": "array", "title": "Failed Objects", "description": "OPTIONAL. List of per-object failure records from batch processing. Populated when individual objects fail while others succeed. Each record includes the object_id, error message, error classification (transient/permanent/resource), and timestamp. When this list is non-empty and some objects succeeded, batch status is COMPLETED_WITH_ERRORS. Enables targeted resubmission of only failed objects.", "examples": [ [], [ { "error": "Unsupported codec: VP9", "error_type": "permanent", "object_id": "obj_video_001", "timestamp": "2025-11-29T10:15:30Z" }, { "error": "Connection timeout to embedding service", "error_type": "transient", "object_id": "obj_doc_123", "timestamp": "2025-11-29T10:15:35Z" } ] ] }, "failed_object_count": { "type": "integer", "minimum": 0.0, "title": "Failed Object Count", "description": "OPTIONAL. Count of objects that failed during batch processing. Shorthand for len(failed_objects). Stored separately for efficient queries and sorting without loading full failed_objects array.", "default": 0, "examples": [ 0, 3, 15 ] }, "unaccounted_object_count": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Unaccounted Object Count", "description": "BACKE-3079: objects that produced NEITHER a document NOR a failure entry \u2014 the per-tier balance audits' summed `lost` (submitted - processed - failed - skipped), rolled up at completion so the gap is STATED on the record instead of inferred by subtraction. None when every submitted object is accounted for; per-tier detail lives at tier_tasks[].audit.", "examples": [ 38 ] }, "type": { "$ref": "#/components/schemas/BatchType", "description": "OPTIONAL (defaults to BUCKET). Type of batch. BUCKET: Standard batch processing bucket objects through collections. COLLECTION: Reserved for future collection-only batch processing. Currently only BUCKET type is supported.", "default": "BUCKET", "examples": [ "BUCKET" ] }, "manifest_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Manifest Key", "description": "OPTIONAL. S3 key where the batch manifest is stored. Contains metadata and row data (Parquet) for Engine processing. For tier 0, points to bucket object manifest. For tier N+, points to collection document manifest. Format: S3 path (e.g., 'namespace_id/internal_id/manifests/tier_0.parquet'). Generated during batch submission.", "examples": [ "ns_abc/org_123/manifests/tier_0.parquet", "ns_xyz/org_456/manifests/tier_1.parquet" ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "OPTIONAL. Primary task ID for the batch (typically tier 0 task). Used for backward compatibility with single-tier batch tracking. For multi-tier batches, prefer querying tier_tasks array for granular tracking. Format: Task ID as generated for tier 0.", "examples": [ "task_tier0_abc123", "task_batch_001" ] }, "loaded_object_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Loaded Object Ids", "description": "OPTIONAL. List of object IDs that were successfully validated and loaded into the batch. Subset of object_ids that passed validation. Used to track which objects are ready for processing. None if batch hasn't been validated yet.", "examples": [ [ "obj_video_001", "obj_video_002" ] ] }, "internal_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Internal Metadata", "description": "OPTIONAL. Internal engine/job metadata for system use. May contain: job_id (provider-specific), engine_version, processing hints, last_health_check. last_health_check: Most recent health check results with health_status, enriched_documents, vector_populated_count, stall_duration_seconds, recommendations, missing_features. Populated asynchronously (non-blocking, best-effort). Used for troubleshooting batch processing issues via API. NOTE: In MongoDB, this is stored under '_internal.processing' path.", "examples": [ { "include_history": true, "last_health_check": { "enriched_documents": 98, "health_status": "HEALTHY", "missing_features": [ "text_embedding" ], "processed_documents": 100, "recommendations": [], "stall_duration_seconds": 0, "timestamp": "2025-11-06T10:05:00Z", "total_documents": 100, "vector_populated_count": 98 } } ] }, "metadata": { "$ref": "#/components/schemas/BatchMetadata", "description": "OPTIONAL. User-defined metadata for the batch. Has typed fields (campaign_id, source, tags, notes) and also accepts arbitrary extra keys. Persisted with the batch and returned in API responses. Not used by the system for processing logic.", "examples": [ { "campaign_id": "Q4_2025", "tags": [ "video", "high-priority" ] }, { "notes": "TubeScience daily ingest", "source": "s3://raw-uploads/2026-05/" } ] }, "tier_tasks": { "items": { "$ref": "#/components/schemas/TierTaskInfo" }, "type": "array", "title": "Tier Tasks", "description": "OPTIONAL. List of tier task tracking information for multi-tier processing. Each element represents one tier in the processing pipeline. Empty array for simple single-tier batches. Populated during batch submission with tier 0 info, then appended as tiers progress. Each TierTaskInfo contains: tier_num, task_id, status, collection_ids, timestamps. Used for granular monitoring: 'Show me status of tier 2' or 'Retry tier 1'. Array index typically matches tier_num (tier_tasks[0] = tier 0, tier_tasks[1] = tier 1, etc.).", "examples": [ [], [ { "collection_ids": [ "col_chunks" ], "status": "COMPLETED", "task_id": "task_tier0_abc", "tier_num": 0 } ] ] }, "current_tier": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Current Tier", "description": "OPTIONAL. Zero-based index of the currently processing tier. None if batch hasn't started processing (status=DRAFT or PENDING). Updated as batch progresses through tiers. Used to show processing progress: 'Processing tier 2 of 5'. Set to last tier number when batch completes. Example: If processing tier 1 (frames), current_tier=1.", "examples": [ 0, 1, 2 ] }, "total_tiers": { "type": "integer", "minimum": 1.0, "title": "Total Tiers", "description": "OPTIONAL (defaults to 1). Total number of tiers in the collection DAG. Minimum 1 (tier 0 only = bucket \u2192 collection). Set during DAG resolution when batch is submitted. Equals len(dag_tiers) if dag_tiers is populated. Used to calculate progress: current_tier / total_tiers. Example: 5-tier pipeline (bucket \u2192 chunks \u2192 frames \u2192 scenes \u2192 summaries) has total_tiers=5.", "default": 1, "examples": [ 1, 3, 5 ] }, "dag_tiers": { "anyOf": [ { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Dag Tiers", "description": "OPTIONAL. Complete DAG tier structure for this batch. List of tiers, where each tier is a list of collection IDs to process at that stage. Tier 0 = bucket-sourced collections. Tier N (N > 0) = collection-sourced collections. Collections within same tier have no dependencies (can run in parallel). Collections in tier N+1 depend on collections in tier N. Populated during DAG resolution at batch submission. Used for tier-by-tier processing orchestration. Example: [['col_chunks'], ['col_frames', 'col_objects'], ['col_scenes']] = 3 tiers where frames and objects run in parallel at tier 1.", "examples": [ [ [ "col_chunks" ] ], [ [ "col_chunks" ], [ "col_frames" ] ], [ [ "col_chunks" ], [ "col_frames", "col_objects" ], [ "col_scenes" ] ] ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "OPTIONAL (auto-set on creation). ISO 8601 timestamp when batch was created. Set using current_time() from shared.utilities.helpers. Immutable after creation. Used for batch age tracking and cleanup of old batches.", "examples": [ "2025-11-03T10:00:00Z" ] }, "progress": { "anyOf": [ { "$ref": "#/components/schemas/BatchProgress" }, { "type": "null" } ], "description": "OPTIONAL. Live progress snapshot updated approximately every 10 seconds while the batch is IN_PROGRESS. Written by the Ray ProgressActor inside the engine job. None when status is DRAFT or PENDING (job not started), or after COMPLETED/FAILED. Use this to show real-time progress bars: processed/total objects, percent complete, throughput (items_per_second), and estimated time remaining (eta_seconds).", "examples": [ null, { "batch_count": 703, "errors": 0, "eta_seconds": 7308.0, "items_per_second": 12.5, "percent": 33.0, "processed": 45000, "total": 136356 } ] }, "documents_written": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Documents Written", "description": "OPTIONAL. Read-time aggregate of documents_written from tier_tasks and extractor_jobs. None means the completion callback has not reported write accounting yet.", "examples": [ null, 1000 ] }, "pages_dropped": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pages Dropped", "description": "OPTIONAL. Read-time aggregate of pages NOT indexed across extractor jobs \u2014 multi-page inputs (PDFs) capped by max_document_pages or dropped by per-page failures. Only present when > 0: a COMPLETED batch with pages_dropped > 0 indexed its inputs PARTIALLY. See pages_dropped_reasons; raise the collection's max_document_pages to index more pages.", "examples": [ null, 10, 355 ] }, "pages_dropped_reasons": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Pages Dropped Reasons", "description": "OPTIONAL. Read-time aggregate of dropped-page counts by reason: max_document_pages_cap (input exceeded the collection's max_document_pages) or page_processing_failure (per-page extract/embed errors).", "examples": [ null, { "max_document_pages_cap": 10 } ] }, "segments_dropped": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Segments Dropped", "description": "OPTIONAL. Read-time aggregate of video segments NOT indexed across extractor jobs \u2014 videos capped by max_video_segments. Only present when > 0: a COMPLETED batch with segments_dropped > 0 indexed its videos PARTIALLY. See segments_dropped_reasons; raise max_video_segments to cover more of each video.", "examples": [ null, 5 ] }, "segments_dropped_reasons": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Segments Dropped Reasons", "description": "OPTIONAL. Read-time aggregate of dropped-segment counts by reason: config_cap_max_video_segments (video exceeded the collection's max_video_segments).", "examples": [ null, { "config_cap_max_video_segments": 5 } ] }, "status_diagnostics": { "additionalProperties": true, "type": "object", "title": "Status Diagnostics", "description": "Read-time diagnostics explaining terminal status, error indicators, and document-write accounting." }, "documents_resolvable": { "type": "boolean", "title": "Documents Resolvable", "description": "ALWAYS PRESENT (BACKE-2960). True only after the server CONFIRMED this terminal batch's just-written documents are actually queryable via the filtered document get path: a confirmation, never a prediction, timestamp, or elapsed time. A COMPLETED batch with documents_resolvable=false is still finalizing: its documents may 404 on direct GET even though they are durable (Studio renders status==COMPLETED && documents_resolvable==false as a 'Finalizing, indexing your results' state and keeps polling). Batches created before the feature shipped emit true (historical, long since resolvable); post-ship batches with no stored value emit false (fail toward not-ready). If the bounded post-completion confirm cannot succeed, documents_resolvable_error is set and this flag stays false.", "default": false }, "documents_resolvable_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documents Resolvable Error", "description": "Terminal failure signal for the bounded resolvability confirm (BACKE-2960/BACKE-2987). Set when the post-completion confirm loop could not confirm this batch's documents were queryable within its bound, the case where documents may NEVER become resolvable. When set, documents_resolvable stays false and will not flip: stop polling and surface a 'taking longer than expected' state instead of a spinner. Null while the confirm is pending or after it succeeded." }, "health": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Health", "description": "OPTIONAL. Computed health status for actively processing batches. Only populated when status is PROCESSING or IN_PROGRESS. Values: 'healthy' (recent activity detected), 'stalled' (no activity for 5+ minutes), 'unknown' (no heartbeat data yet). Computed from tier_tasks[].last_activity_at and updated_at. Use this to detect stuck batches before the internal stall detector kills them.", "examples": [ "healthy", "stalled", "unknown", null ] }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/BatchCost" }, { "type": "null" } ], "description": "OPTIONAL. Dollar cost of this batch, derived at read time from the credits recorded against it in usage_records (credits_consumed * $0.001/credit). Lets callers answer 'what did this batch cost?' from the batch response without GCP billing labels. None when cost could not be looked up (e.g. the usage store was unavailable); 0 credits/USD when no usage has been recorded for the batch yet." }, "last_activity_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Activity At", "description": "OPTIONAL. Timestamp of the most recent activity across all tier tasks. Aggregated from tier_tasks[].last_activity_at \u2014 the latest heartbeat from any tier. Updated approximately every 10 seconds by the BatchJobPoller while processing. A stale value (minutes old) while status is PROCESSING indicates the batch may be stalled. None for batches that have not started processing or have no heartbeat data." }, "retry_count": { "type": "integer", "minimum": 0.0, "title": "Retry Count", "description": "OPTIONAL (defaults to 0). Number of times this batch has been auto-retried due to transient infrastructure failures (spot node preemption, OOM, actor death). Incremented each time the batch is automatically requeued after a retryable failure. User-facing: lets users see that retries happened transparently.", "default": 0, "examples": [ 0, 1, 2, 3 ] }, "max_retries": { "type": "integer", "minimum": 0.0, "title": "Max Retries", "description": "OPTIONAL (defaults to 3). Maximum number of automatic retries for transient failures. When retry_count reaches max_retries, the batch stays in FAILED state. Only transient/infrastructure failures trigger retries \u2014 validation and data errors do not.", "default": 3, "examples": [ 3, 5 ] }, "last_retry_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Retry At", "description": "OPTIONAL. ISO 8601 timestamp of the most recent auto-retry attempt. None if the batch has never been retried. Used to calculate exponential backoff for subsequent retries.", "examples": [ null, "2025-11-03T10:35:00Z" ] }, "retry_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retry Reason", "description": "OPTIONAL. Human-readable reason for the most recent auto-retry. None if the batch has never been retried. Describes the transient failure that triggered the retry (e.g., 'Spot node preempted', 'Ray actor died', 'OOM killed').", "examples": [ null, "Spot node preempted", "Ray actor died unexpectedly", "Worker node evicted (OOM)" ] }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "OPTIONAL. URL to receive an HTTP POST notification when the batch reaches a terminal state (COMPLETED, FAILED, or CANCELED). Set at submit time via SubmitBatchRequest. The webhook is fire-and-forget: delivery failures are logged but never affect batch processing.", "examples": [ "https://example.com/webhooks/batch-complete", null ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "OPTIONAL (auto-updated). ISO 8601 timestamp when batch was last modified. Updated using current_time() whenever batch status or tier_tasks change. Used to track batch activity and identify stale batches.", "examples": [ "2025-11-03T10:30:00Z" ] }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Message", "description": "COMPUTED. Human-readable description of the current batch state. Examples: 'Processing 724/50,000 objects (1.4%)', 'Queued \u2014 2 batches ahead', 'Completed in 5m 23s', 'Loading model (stage 1/3)'. Computed on read, not stored in the database." }, "estimated_completion": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Estimated Completion", "description": "COMPUTED. Estimated completion timestamp based on current throughput. Derived from progress.eta_seconds + now. None if throughput data is unavailable. Computed on read, not stored in the database." } }, "type": "object", "required": [ "bucket_id" ], "title": "BatchModel", "description": "Model representing a batch of objects for processing through collections.\n\nA batch groups bucket objects together for processing through one or more collections.\nBatches support multi-tier processing where collections are processed in dependency order\n(e.g., bucket \u2192 chunks \u2192 frames \u2192 scenes). Each tier has independent task tracking.\n\nUse Cases:\n - Process multiple objects through collections in a single batch\n - Track progress of multi-tier decomposition pipelines\n - Monitor and retry individual processing tiers\n - Query batch status and tier-specific task information\n\nLifecycle:\n 1. Created in DRAFT status with object_ids\n 2. Submitted for processing \u2192 status changes to PENDING\n 3. Each tier processes sequentially (tier 0 \u2192 tier 1 \u2192 ... \u2192 tier N)\n 4. Batch completes when all tiers finish (status=COMPLETED) or any tier fails (status=FAILED)\n\nMulti-Tier Processing:\n - Tier 0: Bucket objects \u2192 Collections (bucket as source)\n - Tier N (N > 0): Collection documents \u2192 Collections (upstream collection as source)\n - Each tier gets independent task tracking via tier_tasks array\n - Processing proceeds tier-by-tier with automatic chaining\n\nRequirements:\n - batch_id: OPTIONAL (auto-generated if not provided)\n - bucket_id: REQUIRED\n - status: OPTIONAL (defaults to DRAFT)\n - object_ids: REQUIRED for processing (must have at least 1 object)\n - collection_ids: OPTIONAL (discovered via DAG resolution)\n - tier_tasks: OPTIONAL (populated during processing)\n - current_tier: OPTIONAL (set during processing)\n - total_tiers: OPTIONAL (defaults to 1, set during DAG resolution)\n - dag_tiers: OPTIONAL (populated during DAG resolution)", "examples": [ { "batch_id": "btch_simple_001", "bucket_id": "bkt_videos", "collection_ids": [ "col_chunks" ], "dag_tiers": [ [ "col_chunks" ] ], "description": "Simple single-tier batch (DRAFT)", "metadata": { "campaign_id": "Q4_2025" }, "object_ids": [ "obj_video_001", "obj_video_002" ], "status": "DRAFT", "tier_tasks": [], "total_tiers": 1, "type": "BUCKET" }, { "batch_id": "btch_multitier_002", "bucket_id": "bkt_videos", "collection_ids": [ "col_chunks", "col_frames", "col_scenes" ], "current_tier": 1, "dag_tiers": [ [ "col_chunks" ], [ "col_frames" ], [ "col_scenes" ] ], "description": "Multi-tier batch (IN_PROGRESS): Currently processing tier 1", "manifest_key": "ns_abc/org_123/manifests/tier_1.parquet", "metadata": { "user_email": "user@example.com" }, "object_ids": [ "obj_video_001" ], "status": "IN_PROGRESS", "task_id": "task_tier0_abc123", "tier_tasks": [ { "collection_ids": [ "col_chunks" ], "completed_at": "2025-11-03T10:05:00Z", "source_type": "bucket", "started_at": "2025-11-03T10:00:00Z", "status": "COMPLETED", "task_id": "task_tier0_abc123", "tier_num": 0 }, { "collection_ids": [ "col_frames" ], "parent_task_id": "task_tier0_abc123", "source_collection_ids": [ "col_chunks" ], "source_type": "collection", "started_at": "2025-11-03T10:05:00Z", "status": "IN_PROGRESS", "task_id": "task_tier1_def456", "tier_num": 1 }, { "collection_ids": [ "col_scenes" ], "source_collection_ids": [ "col_frames" ], "source_type": "collection", "status": "PENDING", "tier_num": 2 } ], "total_tiers": 3, "type": "BUCKET" }, { "batch_id": "btch_complete_003", "bucket_id": "bkt_videos", "collection_ids": [ "col_chunks", "col_frames", "col_scenes" ], "current_tier": 2, "dag_tiers": [ [ "col_chunks" ], [ "col_frames" ], [ "col_scenes" ] ], "description": "Multi-tier batch (COMPLETED): All 3 tiers finished", "object_ids": [ "obj_video_001" ], "status": "COMPLETED", "tier_tasks": [ { "collection_ids": [ "col_chunks" ], "completed_at": "2025-11-03T10:05:00Z", "status": "COMPLETED", "task_id": "task_tier0_abc", "tier_num": 0 }, { "collection_ids": [ "col_frames" ], "completed_at": "2025-11-03T10:10:00Z", "status": "COMPLETED", "task_id": "task_tier1_def", "tier_num": 1 }, { "collection_ids": [ "col_scenes" ], "completed_at": "2025-11-03T10:15:00Z", "status": "COMPLETED", "task_id": "task_tier2_ghi", "tier_num": 2 } ], "total_tiers": 3, "type": "BUCKET" }, { "batch_id": "btch_failed_004", "bucket_id": "bkt_videos", "collection_ids": [ "col_chunks", "col_frames" ], "current_tier": 1, "dag_tiers": [ [ "col_chunks" ], [ "col_frames" ] ], "description": "Multi-tier batch (FAILED): Tier 1 failed with dependency error", "error": "Tier 1 failed: Missing required package: google-genai", "error_summary": { "authentication": 2, "dependency": 5 }, "object_ids": [ "obj_video_001" ], "status": "FAILED", "tier_tasks": [ { "collection_ids": [ "col_chunks" ], "completed_at": "2025-11-03T10:05:00Z", "errors": [], "status": "COMPLETED", "task_id": "task_tier0_abc", "tier_num": 0 }, { "collection_ids": [ "col_frames" ], "completed_at": "2025-11-03T10:06:30Z", "error_summary": { "authentication": 2, "dependency": 5 }, "errors": [ { "affected_count": 5, "component": "VertexMultimodalService", "error_type": "dependency", "message": "Missing required package: google-genai", "recovery_suggestion": "Install google-genai package", "stage": "gemini_extraction" }, { "affected_count": 2, "component": "VertexMultimodalService", "error_type": "authentication", "message": "Invalid Vertex AI credentials" } ], "status": "FAILED", "task_id": "task_tier1_def", "tier_num": 1 } ], "total_tiers": 2, "type": "BUCKET" } ] }, "BatchOptions": { "properties": { "batch_size": { "type": "integer", "maximum": 1000.0, "minimum": 1.0, "title": "Batch Size", "description": "Documents per batch", "default": 100 }, "max_workers": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Max Workers", "description": "Maximum parallel workers", "default": 10 }, "retry_failed": { "type": "boolean", "title": "Retry Failed", "description": "Retry failed batches", "default": true } }, "type": "object", "title": "BatchOptions", "description": "Options for batch processing in migration." }, "BatchPhaseDetail": { "properties": { "processed": { "type": "integer", "title": "Processed", "description": "Items completed in this phase.", "default": 0 }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Items expected in this phase; null when indeterminate." }, "status": { "type": "string", "title": "Status", "description": "Phase status: 'pending', 'active', 'done', or 'error'.", "default": "pending", "examples": [ "pending", "active", "done", "error" ] } }, "type": "object", "title": "BatchPhaseDetail", "description": "Per-phase progress for one streaming phase (BACKE-762).\n\nRay Data streams, so extraction and write run concurrently. Each phase\ncarries its own honest counters. ``status`` is one of pending|active|\ndone|error. Exactly one phase is ``active`` at a time, and it matches\n``BatchStageInfo.name``. ``total`` is null when indeterminate (the write\nphase stays null until extraction drains \u2014 expanding pipelines emit N\noutput points per input object)." }, "BatchPhases": { "properties": { "dispatch": { "$ref": "#/components/schemas/BatchPhaseDetail" }, "extraction": { "$ref": "#/components/schemas/BatchPhaseDetail" }, "write": { "$ref": "#/components/schemas/BatchPhaseDetail" } }, "type": "object", "title": "BatchPhases", "description": "Honest streaming-phase breakdown (BACKE-762) \u2014 the SOLE per-stage source.\n\ndispatch \u2192 extraction \u2192 write. Exactly one phase is ``active``, and its key\nequals ``BatchStageInfo.name``. Consumed by Studio's BatchProgressDetail." }, "BatchProgress": { "properties": { "processed": { "type": "integer", "title": "Processed", "description": "Number of objects fully processed so far.", "default": 0 }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total objects to process. None until the dataset is loaded by the engine." }, "percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percent", "description": "Completion percentage (0\u2013100). None until total is known." }, "items_per_second": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Items Per Second", "description": "Current throughput. Averaged over elapsed time since job start." }, "eta_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Eta Seconds", "description": "Estimated seconds remaining. None until both total and throughput are known." }, "batch_count": { "type": "integer", "title": "Batch Count", "description": "Number of Ray map_batch micro-batches completed.", "default": 0 }, "errors": { "type": "integer", "title": "Errors", "description": "Number of items that errored during processing.", "default": 0 }, "first_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Error", "description": "First item-level error captured during processing (truncated to ~500 chars), e.g. 'ValueError: cannot embed empty text'. Explains WHAT the `errors` counter is counting. None when no item-level error has been captured (or the engine image pre-dates this field). See also batch-level error_summary (error-type counts) and failed_objects (per-object detail)." }, "extraction_first_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extraction First Error", "description": "First map/extraction-stage error (rows dropped before the datasink). Distinct from datasink write errors. Typically equals first_error unless a later write-stage error was also captured." }, "documents_skipped": { "type": "integer", "title": "Documents Skipped", "description": "Number of input rows the processor explicitly marked skipped (metadata-only objects, missing required embedding fields, content-flag filtered, null-text chunks). Skipped rows are not failures and not successes; they count toward the tier-completion invariant via the audit. Phase 1.3 of INGESTION_RELIABILITY_PLAN.md.", "default": 0 }, "current_stage": { "anyOf": [ { "$ref": "#/components/schemas/BatchStageInfo" }, { "type": "null" } ], "description": "Current processing stage as reported by the Ray engine. Populated once the engine begins work (may lag by ~10s). Useful to distinguish 'loading model' from 'no activity' during early processing." }, "phases": { "anyOf": [ { "$ref": "#/components/schemas/BatchPhases" }, { "type": "null" } ], "description": "Honest streaming-phase breakdown (BACKE-762): dispatch \u2192 extraction \u2192 write, each with its own processed/total/status. Exactly one phase is 'active' and its key equals current_stage.name. The SOLE per-stage source of truth \u2014 use this rather than current_stage for per-phase counters. None on engine images that pre-date this field." }, "active_step": { "anyOf": [ { "$ref": "#/components/schemas/BatchStepInfo" }, { "type": "null" } ], "description": "Active pipeline step for multi-step extractors. Shows which processor is currently running (e.g., 'GroundingDINOProcessor 1/3'). None for single-step pipelines." }, "overshoot_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Overshoot Percent", "description": "When processed exceeds total (due to Ray Data retries or pipeline data expansion), this field shows the excess percentage above 100%. For example, 32.0 means 132% of items have been processed. None when processed <= total." }, "queue_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Queue Position", "description": "1-based position in the Ray job submission queue. Non-null only while the batch is waiting for a concurrency slot. Once a slot is acquired (job submitted to Ray), this becomes null." }, "stage_history": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Stage History", "description": "Completed stage timing breakdown. Each entry: name, index, total, started_at (epoch), ended_at (epoch), duration_seconds. Populated as stages complete; the current (in-progress) stage is in current_stage." }, "documents_written": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Documents Written", "description": "Derived documents written across completed tier/extractor jobs." }, "chunk_stats": { "anyOf": [ { "$ref": "#/components/schemas/BatchChunkStats" }, { "type": "null" } ], "description": "Realized chunking statistics (unit, total_chunks, mean units per chunk) reported by the text chunker. None for non-chunking extractors or engine images that pre-date this field." }, "status_warnings": { "items": { "type": "string" }, "type": "array", "title": "Status Warnings", "description": "Read-time warnings that explain ambiguous terminal status or accounting gaps." } }, "type": "object", "title": "BatchProgress", "description": "Live progress snapshot written by ProgressPoller every ~10 seconds while a batch is IN_PROGRESS.\n\nPopulated by the Ray ProgressActor running inside the engine job.\nNone when the batch has not started processing yet (DRAFT/PENDING) or if the engine\nimage pre-dates this field." }, "BatchQueryItem": { "properties": { "inputs": { "additionalProperties": true, "type": "object", "title": "Inputs", "description": "Runtime inputs for this query (e.g., {'query': 'https://example.com/img.jpg'})" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters", "description": "Optional per-query filters." } }, "type": "object", "required": [ "inputs" ], "title": "BatchQueryItem", "description": "A single query within a batch execution request." }, "BatchStageInfo": { "properties": { "name": { "type": "string", "title": "Name", "description": "Honest active streaming phase: 'dispatch', 'extraction', or 'write' (BACKE-762). Equals the one phase in BatchProgress.phases whose status is 'active'.", "examples": [ "dispatch", "extraction", "write" ] }, "index": { "type": "integer", "title": "Index", "description": "1-based stage index within the current job." }, "total": { "type": "integer", "title": "Total", "description": "Total stages in the current job." }, "stage_elapsed_seconds": { "type": "number", "title": "Stage Elapsed Seconds", "description": "Seconds spent in this stage so far.", "default": 0.0 }, "sub_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sub Stage", "description": "Sub-stage within 'processing': 'model_loading' while models are initializing, 'inferring' once the first batch completes. Helps explain why processed=0.", "examples": [ "model_loading", "inferring" ] } }, "type": "object", "required": [ "name", "index", "total" ], "title": "BatchStageInfo", "description": "Current processing stage reported by the Ray engine.\n\nBACKE-762: ``name`` is now the honest *active* streaming phase \u2014\n\"dispatch\" \u2192 \"extraction\" \u2192 \"write\" \u2014 derived from the phase machine\n(the true bottleneck), NOT the premature \"writing\" label that the\ndatasink used to emit on the first row. It is a LABEL ONLY; per-phase\ncounters live in ``BatchProgress.phases``. ``index``/``total`` stay as\nN-of-3. The stage name resets the stall timer, so users can see *what*\nthe job is doing even when processed=0 (e.g., waiting for a model load)." }, "BatchStatistics": { "properties": { "total": { "type": "integer", "title": "Total", "description": "Total number of batches in this bucket", "default": 0 }, "active": { "type": "integer", "title": "Active", "description": "Number of batches that are not completed (DRAFT, PENDING, IN_PROGRESS, PROCESSING)", "default": 0 }, "completed": { "type": "integer", "title": "Completed", "description": "Number of completed batches", "default": 0 }, "failed": { "type": "integer", "title": "Failed", "description": "Number of failed batches", "default": 0 } }, "type": "object", "title": "BatchStatistics", "description": "Statistics about batches in a bucket." }, "BatchStepInfo": { "properties": { "name": { "type": "string", "title": "Name", "description": "Processor class name (e.g., 'GroundingDINOProcessor', 'SigLIPProcessor')." }, "index": { "type": "integer", "title": "Index", "description": "1-based step index within the pipeline." }, "total": { "type": "integer", "title": "Total", "description": "Total number of steps in the pipeline." }, "step_elapsed_seconds": { "type": "number", "title": "Step Elapsed Seconds", "description": "Seconds spent in this step so far." } }, "type": "object", "required": [ "name", "index", "total", "step_elapsed_seconds" ], "title": "BatchStepInfo", "description": "Active pipeline step for multi-step extractors (e.g., GroundingDINO \u2192 SigLIP).\n\nSurfaces which step is currently running and its position in the pipeline,\nso users can track progress through complex multi-model pipelines." }, "BatchType": { "type": "string", "enum": [ "BUCKET", "COLLECTION" ], "title": "BatchType", "description": "The type of batch." }, "BatchUpdateDocumentsRequest": { "properties": { "updates": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BatchDocumentUpdate" }, "type": "array", "maxItems": 1000, "minItems": 1 }, { "type": "null" } ], "title": "Updates", "description": "OPTIONAL. List of document updates with explicit document IDs. Each entry specifies document_id and update_data. Use this mode when you know exact document IDs and want per-document control. Mutually exclusive with filters + update_data mode. Maximum 1000 documents per batch request.", "examples": [ [ { "document_id": "doc_123", "update_data": { "metadata": { "status": "processed" } } }, { "document_id": "doc_456", "update_data": { "metadata": { "status": "archived" } } } ] ] }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "OPTIONAL. Filter conditions to match documents for update. Must be used with 'update_data' field. Mutually exclusive with 'updates' array. If provided, applies same update_data to all matching documents." }, "update_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Update Data", "description": "OPTIONAL. Update data to apply when using filters mode. Must be used with 'filters' field. All matched documents receive the same updates. Can update any document field except vectors." } }, "type": "object", "title": "BatchUpdateDocumentsRequest", "description": "Request model for batch updating multiple documents by explicit IDs or filters.\n\nSupports TWO modes:\n1. Explicit IDs mode: Provide 'updates' array with document_id + update_data for each\n2. Filter mode: Provide 'filters' + 'update_data' to update all matching documents\n\nKey difference from BulkUpdateDocumentsRequest:\n- Batch (this): Can apply DIFFERENT updates to SPECIFIC documents by ID\n- Bulk: Applies SAME update to ALL documents matching filters\n\nUse Cases:\n - Update 5 specific documents with different metadata values\n - Update documents by IDs with per-document update control\n - Combine with filters for targeted batch updates\n\nRequirements:\n - EITHER 'updates' (explicit mode) OR 'filters' + 'update_data' (filter mode)\n - NOT BOTH modes simultaneously", "examples": [ { "description": "Explicit IDs mode: Update 3 documents with different values", "updates": [ { "document_id": "doc_frame_001", "update_data": { "metadata": { "quality_score": 0.95, "reviewed": true } } }, { "document_id": "doc_frame_002", "update_data": { "metadata": { "flagged": true, "quality_score": 0.87 } } }, { "document_id": "doc_frame_003", "update_data": { "metadata": { "discarded": true, "quality_score": 0.72 } } } ] }, { "description": "Filter mode: Update all pending documents", "filters": { "AND": [ { "field": "metadata.status", "operator": "eq", "value": "pending" } ] }, "update_data": { "metadata": { "status": "processed" } } } ] }, "BatchUpdateDocumentsResponse": { "properties": { "updated_count": { "type": "integer", "title": "Updated Count", "description": "Total number of documents successfully updated" }, "failed_count": { "type": "integer", "title": "Failed Count", "description": "Total number of documents that failed to update", "default": 0 }, "results": { "items": { "$ref": "#/components/schemas/BatchDocumentUpdateResult" }, "type": "array", "title": "Results", "description": "Detailed per-document results. Each entry shows document_id, success status, and error message (if failed). Empty list when using filter mode (only counts returned)." }, "message": { "type": "string", "title": "Message", "description": "Summary message of the operation", "default": "Batch update completed" } }, "type": "object", "required": [ "updated_count" ], "title": "BatchUpdateDocumentsResponse", "description": "Response model for batch document update operation.\n\nProvides detailed per-document results showing success/failure for each update.", "examples": [ { "failed_count": 0, "message": "Successfully updated 3 document(s)", "results": [ { "document_id": "doc_123", "success": true }, { "document_id": "doc_456", "success": true }, { "document_id": "doc_789", "success": true } ], "updated_count": 3 } ] }, "BatchUploadRequest": { "properties": { "uploads": { "items": { "$ref": "#/components/schemas/CreateUploadRequest" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Uploads", "description": "List of upload requests (max 100)" }, "shared_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Shared Metadata", "description": "Metadata to apply to all uploads (merged with individual metadata)" }, "shared_object_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Shared Object Metadata", "description": "Object metadata to apply to all uploads (merged with individual)" } }, "type": "object", "required": [ "uploads" ], "title": "BatchUploadRequest", "description": "Request to generate multiple presigned URLs in a single request.", "examples": [ { "shared_metadata": { "campaign": "summer_2024" }, "shared_object_metadata": { "category": "marketing" }, "uploads": [ { "blob_property": "video", "content_type": "video/mp4", "filename": "video1.mp4" }, { "blob_property": "thumbnail", "content_type": "image/jpeg", "filename": "thumbnail1.jpg" } ] } ] }, "BatchUploadResponse": { "properties": { "uploads": { "items": { "$ref": "#/components/schemas/UploadResponse" }, "type": "array", "title": "Uploads", "description": "Generated uploads with presigned URLs" }, "total": { "type": "integer", "title": "Total", "description": "Total number of uploads created" } }, "type": "object", "required": [ "uploads", "total" ], "title": "BatchUploadResponse", "description": "Response from batch upload request.", "examples": [ { "total": 2, "uploads": [ { "filename": "video1.mp4", "presigned_url": "https://s3.amazonaws.com/...", "status": "PENDING", "upload_id": "upl_abc123" } ] } ] }, "BatchingConfig": { "properties": { "mode": { "type": "string", "enum": [ "time_window", "count", "immediate" ], "title": "Mode", "default": "time_window" }, "window_seconds": { "type": "integer", "maximum": 300.0, "minimum": 5.0, "title": "Window Seconds", "default": 30 }, "max_batch_size": { "type": "integer", "maximum": 1000.0, "minimum": 1.0, "title": "Max Batch Size", "default": 100 }, "auto_submit": { "type": "boolean", "title": "Auto Submit", "default": true } }, "type": "object", "title": "BatchingConfig" }, "BenchmarkComparison": { "properties": { "baseline_retriever_id": { "type": "string", "title": "Baseline Retriever Id", "description": "ID of the baseline pipeline." }, "comparisons": { "items": { "$ref": "#/components/schemas/PipelineComparison" }, "type": "array", "title": "Comparisons", "description": "Comparison results for each candidate." }, "recommendation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recommendation", "description": "System-generated recommendation based on results." } }, "type": "object", "required": [ "baseline_retriever_id", "comparisons" ], "title": "BenchmarkComparison", "description": "Comparison of all candidates against the baseline." }, "BenchmarkListResponse": { "properties": { "benchmarks": { "items": { "$ref": "#/components/schemas/BenchmarkResponse" }, "type": "array", "title": "Benchmarks", "description": "List of benchmarks." }, "total": { "type": "integer", "title": "Total", "description": "Total count matching filter." }, "page": { "type": "integer", "title": "Page", "description": "Current page.", "default": 1 }, "page_size": { "type": "integer", "title": "Page Size", "description": "Items per page.", "default": 20 } }, "type": "object", "required": [ "benchmarks", "total" ], "title": "BenchmarkListResponse", "description": "Response for listing benchmarks." }, "BenchmarkResponse": { "properties": { "benchmark_id": { "type": "string", "title": "Benchmark Id", "description": "Unique benchmark identifier." }, "benchmark_name": { "type": "string", "title": "Benchmark Name", "description": "Human-readable name." }, "baseline_retriever_id": { "type": "string", "title": "Baseline Retriever Id", "description": "Baseline retriever ID." }, "candidate_retriever_ids": { "items": { "type": "string" }, "type": "array", "title": "Candidate Retriever Ids", "description": "Candidate retriever IDs." }, "session_filter": { "anyOf": [ { "$ref": "#/components/schemas/SessionFilter-Output" }, { "type": "null" } ], "description": "Filter criteria used." }, "session_count": { "type": "integer", "title": "Session Count", "description": "Number of sessions in benchmark." }, "status": { "$ref": "#/components/schemas/BenchmarkStatus", "description": "Current benchmark status." }, "results": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BenchmarkResult" }, "type": "array" }, { "type": "null" } ], "title": "Results", "description": "Results per pipeline (available when completed)." }, "comparison": { "anyOf": [ { "$ref": "#/components/schemas/BenchmarkComparison" }, { "type": "null" } ], "description": "Statistical comparison (available when completed)." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "Execution start time." }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "Completion time." }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Error message if failed." } }, "type": "object", "required": [ "benchmark_id", "benchmark_name", "baseline_retriever_id", "candidate_retriever_ids", "session_count", "status", "created_at" ], "title": "BenchmarkResponse", "description": "Response containing benchmark details and results." }, "BenchmarkResult": { "properties": { "retriever_id": { "type": "string", "title": "Retriever Id", "description": "ID of the retriever/pipeline tested." }, "retriever_name": { "type": "string", "title": "Retriever Name", "description": "Human-readable name of the retriever." }, "pipeline_hash": { "type": "string", "title": "Pipeline Hash", "description": "Hash of the pipeline configuration." }, "metrics": { "$ref": "#/components/schemas/AlignmentMetrics", "description": "Alignment metrics for this pipeline." }, "taxonomy_deltas": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/AlignmentMetrics" }, "type": "object" }, { "type": "null" } ], "title": "Taxonomy Deltas", "description": "Metrics broken down by taxonomy node (for understanding category-level performance)." }, "latency": { "$ref": "#/components/schemas/LatencyMetrics", "description": "Performance timing statistics." }, "failed_sessions": { "type": "integer", "minimum": 0.0, "title": "Failed Sessions", "description": "Number of sessions that failed during replay." }, "error_summary": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Error Summary", "description": "Count of errors by type (error_type -> count)." } }, "type": "object", "required": [ "retriever_id", "retriever_name", "pipeline_hash", "metrics", "latency", "failed_sessions" ], "title": "BenchmarkResult", "description": "Results for a single pipeline in a benchmark run." }, "BenchmarkStatus": { "type": "string", "enum": [ "pending", "building_sessions", "replaying", "computing_metrics", "completed", "failed" ], "title": "BenchmarkStatus", "description": "Status of a benchmark run." }, "BillingPeriodSummary": { "properties": { "billing_month": { "type": "string", "title": "Billing Month" }, "platform_fee_usd": { "type": "number", "title": "Platform Fee Usd", "default": 0.0 }, "compute_base_cost_usd": { "type": "number", "title": "Compute Base Cost Usd", "default": 0.0 }, "usage_cost_usd": { "type": "number", "title": "Usage Cost Usd", "default": 0.0 }, "total_base_cost_usd": { "type": "number", "title": "Total Base Cost Usd", "default": 0.0 }, "note": { "type": "string", "title": "Note", "default": "Base cost before margin" } }, "type": "object", "required": [ "billing_month" ], "title": "BillingPeriodSummary" }, "BillingPortalRequest": { "properties": { "return_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return Url", "description": "URL Stripe redirects back to when the customer leaves the portal", "default": "https://studio.mixpeek.com/billing" } }, "type": "object", "title": "BillingPortalRequest", "description": "Request to open the Stripe customer billing portal." }, "BillingPortalResponse": { "properties": { "portal_url": { "type": "string", "title": "Portal Url", "description": "Stripe-hosted billing portal URL (redirect the user here)", "examples": [ "https://billing.stripe.com/p/session/live_abc123" ] }, "session_id": { "type": "string", "title": "Session Id", "description": "Stripe billing portal session ID", "examples": [ "bps_live_abc123" ] } }, "type": "object", "required": [ "portal_url", "session_id" ], "title": "BillingPortalResponse", "description": "Response with the Stripe-hosted billing portal URL.\n\nThe portal lets an existing customer update their card, view invoices, and\nchange or cancel their subscription \u2014 distinct from /subscribe, which starts\na NEW checkout (re-running checkout for an existing subscriber is wrong)." }, "BlobDetails": { "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mime Type" }, "hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash" } }, "type": "object", "title": "BlobDetails", "description": "File details for a bucket object, these are automatically generated by the system." }, "BlobMappingEntry": { "properties": { "target_type": { "type": "string", "const": "blob", "title": "Target Type", "description": "Target type. Must be 'blob' for blob mappings.", "default": "blob" }, "source": { "oneOf": [ { "$ref": "#/components/schemas/S3TagSource" }, { "$ref": "#/components/schemas/S3MetadataSource" }, { "$ref": "#/components/schemas/FilenameRegexSource" }, { "$ref": "#/components/schemas/ColumnSource" }, { "$ref": "#/components/schemas/DrivePropertySource" }, { "$ref": "#/components/schemas/FolderPathSource" }, { "$ref": "#/components/schemas/FileSource" }, { "$ref": "#/components/schemas/ConstantSource" }, { "$ref": "#/components/schemas/RSSFieldSource" } ], "title": "Source", "description": "Source extractor defining where to get the blob content or URL. Use 'file' for the synced file itself (most common). Use 'column' for database URL columns pointing to external content. Use 'metadata' for S3 metadata containing URLs.", "discriminator": { "propertyName": "type", "mapping": { "column": "#/components/schemas/ColumnSource", "constant": "#/components/schemas/ConstantSource", "drive_property": "#/components/schemas/DrivePropertySource", "file": "#/components/schemas/FileSource", "filename_regex": "#/components/schemas/FilenameRegexSource", "folder_path": "#/components/schemas/FolderPathSource", "metadata": "#/components/schemas/S3MetadataSource", "rss_field": "#/components/schemas/RSSFieldSource", "tag": "#/components/schemas/S3TagSource" } } }, "blob_type": { "$ref": "#/components/schemas/BlobType", "description": "Type of blob content. Determines which extractors can process it. 'auto' (default) infers type from mime_type - recommended for files. Explicit types: 'image', 'video', 'audio', 'text', 'document', 'json', 'binary'. Use explicit types when mime_type detection is unreliable.", "default": "auto" }, "blob_property": { "type": "string", "minLength": 1, "title": "Blob Property", "description": "The blob property name in the bucket schema. This identifies which blob in the object's blobs array. Default: 'content' (the primary blob). Must match a blob property defined in the bucket schema.", "default": "content", "examples": [ "content", "thumbnail", "profile_image", "document", "audio" ] }, "mime_type_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mime Type Override", "description": "Optional mime_type to use instead of auto-detection. Useful when the source doesn't provide accurate mime_type. Format: 'type/subtype' (e.g., 'image/jpeg', 'video/mp4'). When set, this value is used for blob.details.mime_type.", "examples": [ "image/jpeg", "video/mp4", "application/pdf", "audio/mpeg" ] } }, "type": "object", "required": [ "source" ], "title": "BlobMappingEntry", "description": "Maps a source to a blob in the bucket object.\n\nUsed for mapping files or URL references to blob fields. The blob_type\ndetermines how the content is processed by extractors. This is the\nprimary way to map synced files into the Mixpeek extraction pipeline.\n\nExample: Map the synced file to the primary \"content\" blob\n {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"auto\",\n \"blob_property\": \"content\"\n }\n\nExample: Map a database column URL to an image blob\n {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"column\", \"name\": \"AVATAR_URL\"},\n \"blob_type\": \"image\",\n \"blob_property\": \"profile_image\"\n }\n\nExample: Map with explicit mime_type override\n {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"video\",\n \"blob_property\": \"content\",\n \"mime_type_override\": \"video/mp4\"\n }\n\nAttributes:\n target_type: Must be \"blob\" for blob mappings\n source: The source extractor (usually \"file\" for synced content)\n blob_type: Content type hint for extractors (auto, image, video, etc.)\n blob_property: Name of the blob property in the bucket schema\n mime_type_override: Optional explicit mime_type to use" }, "BlobModel": { "properties": { "blob_id": { "type": "string", "title": "Blob Id", "description": "Unique identifier for the blob", "examples": [ "blob_a1b2c3d4e5f6" ] }, "property": { "type": "string", "title": "Property", "description": "Property name of the blob", "examples": [ "video", "thumbnail", "content" ] }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Prefix", "description": "Storage key/path of the blob, this will be used to retrieve the blob from the storage. It is similar to a file path. If not provided, it will be placed in the root of the bucket.", "examples": [ "/videos/video.mp4", "/thumbnails/thumb.jpg" ] }, "type": { "$ref": "#/components/schemas/BucketSchemaFieldType", "description": "The schema field type this blob corresponds to (e.g., IMAGE, PDF, DOCUMENT)", "examples": [ "video", "image", "pdf", "text" ] }, "properties": { "additionalProperties": true, "type": "object", "title": "Properties", "description": "All blob data and metadata unified (formerly separate 'data' and 'metadata' fields). Contains URLs, dimensions, metadata, and any other blob-specific information.", "examples": [ { "author": "John Doe", "duration": 120, "resolution": "1920x1080", "tags": [ "product", "demo" ], "url": "s3://bucket/video.mp4" } ] }, "presigned_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Presigned Url", "description": "Canonical top-level presigned URL for this blob. Matches the shape used by `document_blobs[].presigned_url` on document responses. Populated by the API when `?return_presigned_urls=true`. Also mirrored at `properties.presigned_url` for backward compatibility \u2014 prefer this top-level field; the nested path will be removed in a future release." }, "details": { "$ref": "#/components/schemas/BlobDetails", "description": "System-generated file details (filename, size, hash, etc.)" } }, "type": "object", "required": [ "property", "type" ], "title": "BlobModel", "description": "Model for a blob within a bucket object.\n\nBlobs store file references with a flat properties structure.\nAll blob-specific data (formerly in separate 'data' and 'metadata' fields)\nis now unified in a single 'properties' dictionary.\n\nExample:\n {\n \"blob_id\": \"blob_xyz123\",\n \"property\": \"video\",\n \"type\": \"video\",\n \"properties\": {\n \"url\": \"s3://bucket/video.mp4\",\n \"duration\": 120,\n \"resolution\": \"1920x1080\",\n \"author\": \"John Doe\" # All data unified here\n }\n }" }, "BlobSource": { "properties": { "file_field": { "type": "string", "title": "File Field", "description": "Dot-path into the payload or metadata to extract the downloadable URL" }, "blob_type": { "type": "string", "title": "Blob Type", "description": "Blob type for the bucket schema (video, image, audio, etc.)", "default": "video" }, "target_property": { "type": "string", "title": "Target Property", "description": "Bucket schema field name to store the blob under" } }, "type": "object", "required": [ "file_field", "target_property" ], "title": "BlobSource" }, "BlobType": { "type": "string", "enum": [ "auto", "image", "video", "audio", "text", "pdf", "excel" ], "title": "BlobType", "description": "Type of blob content for schema mapping.\n\nDetermines how the blob content is processed and what extractors can operate on it.\nThis is critical for the extraction pipeline to route content correctly.\n\nValues:\n auto: Automatically infer blob type from mime_type (recommended for files)\n image: Image files (JPEG, PNG, WebP, BMP, TIFF, or GIF as static)\n video: Video files (MP4, MOV, WebM, AVI, MKV, or GIF as animated frames)\n audio: Audio files (MP3, WAV, FLAC, AAC, OGG)\n text: Text files (TXT, MD, HTML, XML)\n pdf: PDF documents\n excel: Spreadsheet files (XLSX, XLS, CSV)\n\n**GIF Special Handling**:\n GIF files are unique - they can be processed as either IMAGE or VIDEO:\n\n - As IMAGE: Single static embedding (first frame), no decomposition\n - As VIDEO: Frame-by-frame decomposition with per-frame embeddings\n\n When using \"auto\", GIFs default to IMAGE. To get frame-level processing\n for animated GIFs, explicitly set blob_type to VIDEO.\n\nUsage Guidelines:\n - Use \"auto\" when syncing files with accurate mime_type headers\n - Use explicit types when mime_type is missing or unreliable\n - Use \"video\" for animated GIFs requiring frame-level search" }, "BlobURLRef": { "properties": { "field": { "type": "string", "minLength": 1, "title": "Field", "description": "REQUIRED. Stable semantic label for this blob. Use descriptive names like 'video_segment', 'thumbnail', 'source_video', etc. Avoid internal implementation details like array indices. This field is used for programmatic access and should be consistent across documents.", "examples": [ "video_segment", "thumbnail", "source_video", "processed_frame" ] }, "role": { "type": "string", "enum": [ "source", "processed", "thumbnail", "artifact", "aux" ], "title": "Role", "description": "REQUIRED. Semantic role determining how this blob should be treated. 'source': Original input media from buckets or uploads. 'processed': Derived content created by feature extractors (segments, frames). 'thumbnail': Preview images for UI display. 'artifact': Generated outputs (reports, analysis results). 'aux': Supporting or auxiliary files. Used by UI for grouping and displaying blobs appropriately.", "default": "source" }, "type": { "type": "string", "enum": [ "video", "image", "audio", "text", "pdf", "other" ], "title": "Type", "description": "REQUIRED. Media type of the blob content. Determines how the blob should be rendered or processed. Use 'other' for custom or unknown types.", "default": "other" }, "url": { "type": "string", "minLength": 1, "title": "Url", "description": "REQUIRED. Permanent URL to the blob content. S3 URLs (s3://bucket/key) are automatically converted to presigned HTTPS URLs by the API. HTTP/HTTPS URLs are returned as-is. This is the canonical reference to the blob that persists across API calls.", "examples": [ "s3://mixpeek-storage/namespace_123/objects/obj_456/segment_0.mp4", "https://example.com/media/video.mp4" ] }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "OPTIONAL. Original filename or leaf name of the blob. Useful for downloads and display purposes. Example: 'segment_0.mp4', 'thumbnail.jpg'", "examples": [ "segment_0.mp4", "thumbnail.jpg", "analysis_report.pdf" ] }, "size_bytes": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Size Bytes", "description": "OPTIONAL. Size of the blob in bytes. Useful for progress indicators and storage tracking.", "examples": [ 1048576, 524288 ] }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type", "description": "OPTIONAL. MIME type of the blob content. Used for proper content-type headers when serving files. Example: 'video/mp4', 'image/jpeg', 'application/pdf'", "examples": [ "video/mp4", "image/jpeg", "image/png", "application/pdf" ] }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checksum", "description": "OPTIONAL. Checksum or hash of the blob content for integrity verification. Format: 'algorithm:hash' (e.g., 'sha256:abc123...')", "examples": [ "sha256:a1b2c3d4e5f6...", "md5:9e107d9d372bb6826bd81d3542a419d6" ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "OPTIONAL. Timestamp when the blob was created or uploaded. ISO 8601 format. Useful for tracking blob lifecycle and cleanup." }, "source_blob_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Blob Id", "description": "OPTIONAL. Cross-reference to the source blob ID from the bucket object. Used for lineage tracking: connects processed blobs back to their original sources. Example: A video segment references the original video blob that it was extracted from.", "examples": [ "blob_abc123", "blob_xyz789" ] }, "presigned_url": { "anyOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Presigned Url", "description": "RESPONSE ONLY. Time-limited HTTPS URL for direct access to the blob. Automatically generated by the API when documents are retrieved. NOT REQUIRED when creating blobs - leave empty, API will populate. Typically expires after 1 hour. Use for immediate media playback or download." } }, "type": "object", "required": [ "field", "url" ], "title": "BlobURLRef", "description": "Reference to a document-related blob with automatic presigned URL generation.\n\nRepresents any file or asset associated with a document, including source media,\nprocessed outputs, thumbnails, and artifacts. All blobs with S3 URLs automatically\nreceive presigned URLs when documents are retrieved from the API.\n\nUse Cases:\n - Track source media: Original videos, images, or files from buckets\n - Reference processed outputs: Video segments, extracted frames, thumbnails\n - Link artifacts: Generated reports, analysis results, derived media\n - Maintain lineage: Connect processed blobs back to their source blobs\n\nRole Definitions:\n - source: Original input media (e.g., uploaded video, bucket object)\n - processed: Derived/transformed content (e.g., video segments, extracted frames)\n - thumbnail: Preview images for visual content\n - artifact: Generated files (reports, analysis outputs)\n - aux: Supporting/auxiliary files\n\nPresigned URL Flow:\n 1. During processing: Store S3 URLs in document_blobs (no presigned URL yet)\n 2. During retrieval: API automatically adds presigned_url field to each blob\n 3. Client receives: Both permanent S3 URL and time-limited HTTPS presigned URL\n\nRequirements:\n - field: REQUIRED. Semantic label for the blob (e.g., 'video_segment', 'thumbnail')\n - url: REQUIRED. S3 or HTTP URL to the blob content\n - role: REQUIRED. Semantic role for UX grouping and behavior\n - All other fields: OPTIONAL but recommended for better tracking", "examples": [ { "content_type": "video/mp4", "description": "Original source video from bucket", "field": "source_video", "role": "source", "size_bytes": 10485760, "source_blob_id": "blob_original123", "type": "video", "url": "s3://mixpeek-storage/ns_123/obj_456/original.mp4" }, { "content_type": "video/mp4", "description": "Processed video segment", "field": "video_segment", "filename": "segment_0.mp4", "object_key": "ns_123/obj_456/segments/segment_0.mp4", "role": "processed", "size_bytes": 524288, "source_blob_id": "blob_original123", "type": "video", "url": "s3://mixpeek-storage/ns_123/obj_456/segments/segment_0.mp4" }, { "content_type": "image/jpeg", "description": "Thumbnail image", "field": "thumbnail", "filename": "thumb_0.jpg", "role": "thumbnail", "size_bytes": 51200, "type": "image", "url": "s3://mixpeek-storage/ns_123/obj_456/thumbs/thumb_0.jpg" } ] }, "Body_advance_funnel_stage_v1_notifications_funnel_advance_post": { "properties": { "stage": { "type": "string", "title": "Stage" } }, "type": "object", "required": [ "stage" ], "title": "Body_advance_funnel_stage_v1_notifications_funnel_advance_post" }, "Body_apply_manifest_v1_manifest_apply_post": { "properties": { "manifest_file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Manifest File", "description": "YAML manifest file" } }, "type": "object", "required": [ "manifest_file" ], "title": "Body_apply_manifest_v1_manifest_apply_post" }, "Body_create_subscription_v1_marketplace_subscriptions_post": { "properties": { "listing_id": { "type": "string", "title": "Listing Id", "description": "Marketplace listing ID" }, "tier": { "$ref": "#/components/schemas/SubscriptionTier", "description": "Subscription tier (free, basic, pro, enterprise)" } }, "type": "object", "required": [ "listing_id", "tier" ], "title": "Body_create_subscription_v1_marketplace_subscriptions_post" }, "Body_diff_manifest_v1_manifest_diff_post": { "properties": { "manifest_file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Manifest File", "description": "YAML manifest file" } }, "type": "object", "required": [ "manifest_file" ], "title": "Body_diff_manifest_v1_manifest_diff_post" }, "Body_generate_invoice_now_v1_organizations_billing_generate_invoice_post": { "properties": { "billing_month": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Month", "description": "Billing month (YYYY-MM). Defaults to previous month." }, "dry_run": { "type": "boolean", "title": "Dry Run", "description": "If true, show what would be invoiced without creating Stripe invoice.", "default": false } }, "type": "object", "title": "Body_generate_invoice_now_v1_organizations_billing_generate_invoice_post" }, "Body_heal_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__heal_post": { "properties": { "action": { "type": "string", "title": "Action", "description": "Self-healing action: 'kill_duplicates', 'detect_stuck', 'sync_status'." } }, "type": "object", "required": [ "action" ], "title": "Body_heal_tier_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__heal_post" }, "Body_lint_manifest_v1_manifest_lint_post": { "properties": { "manifest_file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Manifest File", "description": "YAML manifest file" } }, "type": "object", "required": [ "manifest_file" ], "title": "Body_lint_manifest_v1_manifest_lint_post" }, "Body_upload_model_v1_namespaces__namespace_id__models_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Model archive (.tar.gz)" }, "name": { "type": "string", "title": "Name", "description": "Model name" }, "version": { "type": "string", "title": "Version", "description": "Model version" }, "model_format": { "type": "string", "enum": [ "safetensors", "onnx", "pytorch", "huggingface" ], "title": "Model Format", "description": "Model format" }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "description": "ML framework (e.g., sentence-transformers)" }, "task_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Type", "description": "Task type (e.g., embedding, classification)" }, "num_cpus": { "type": "number", "title": "Num Cpus", "description": "CPU requirements", "default": 1.0 }, "num_gpus": { "type": "integer", "title": "Num Gpus", "description": "GPU requirements", "default": 0 }, "memory_gb": { "type": "number", "title": "Memory Gb", "description": "Memory in GB", "default": 4.0 } }, "type": "object", "required": [ "file", "name", "version", "model_format" ], "title": "Body_upload_model_v1_namespaces__namespace_id__models_post" }, "Body_validate_manifest_v1_manifest_validate_post": { "properties": { "manifest_file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "Manifest File", "description": "YAML manifest file" } }, "type": "object", "required": [ "manifest_file" ], "title": "Body_validate_manifest_v1_manifest_validate_post" }, "Body_verify_marketplace_listing_password_v1_marketplace_catalog__public_name__verify_post": { "properties": { "password": { "type": "string", "title": "Password", "description": "Password to verify" } }, "type": "object", "required": [ "password" ], "title": "Body_verify_marketplace_listing_password_v1_marketplace_catalog__public_name__verify_post" }, "BoolIndexParams": { "properties": { "type": { "type": "string", "title": "Type", "default": "bool" } }, "type": "object", "title": "BoolIndexParams", "description": "Configuration for boolean index." }, "BottleneckAnalysis": { "properties": { "stage_name": { "type": "string", "title": "Stage Name", "description": "Stage name" }, "component": { "type": "string", "title": "Component", "description": "Component" }, "execution_count": { "type": "integer", "title": "Execution Count", "description": "Number of executions" }, "total_time_ms": { "type": "number", "title": "Total Time Ms", "description": "Total time spent" }, "avg_time_ms": { "type": "number", "title": "Avg Time Ms", "description": "Average time per execution" }, "pct_of_total": { "type": "number", "title": "Pct Of Total", "description": "Percentage of total execution time" }, "rank": { "type": "integer", "title": "Rank", "description": "Bottleneck ranking (1 = worst)" } }, "type": "object", "required": [ "stage_name", "component", "execution_count", "total_time_ms", "avg_time_ms", "pct_of_total", "rank" ], "title": "BottleneckAnalysis", "description": "Bottleneck analysis result." }, "BottleneckResponse": { "properties": { "time_range": { "$ref": "#/components/schemas/api__analytics__models__TimeRange", "description": "Time range of the analysis" }, "bottlenecks": { "items": { "$ref": "#/components/schemas/BottleneckAnalysis" }, "type": "array", "title": "Bottlenecks", "description": "Ranked list of bottlenecks" }, "total_time_ms": { "type": "number", "title": "Total Time Ms", "description": "Total execution time across all components" } }, "type": "object", "required": [ "time_range", "bottlenecks", "total_time_ms" ], "title": "BottleneckResponse", "description": "Response for bottleneck analysis." }, "BoxCCGCredentials": { "properties": { "type": { "type": "string", "const": "ccg", "title": "Type", "default": "ccg" }, "client_id": { "type": "string", "title": "Client Id", "description": "REQUIRED. Box application client ID from Developer Console.", "examples": [ "abc123def456ghi789" ] }, "client_secret": { "type": "string", "title": "Client Secret", "description": "REQUIRED. Box application client secret. SECURITY: Encrypted at rest via CSFLE." }, "enterprise_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enterprise Id", "description": "Enterprise ID to authenticate as. Required when using CCG to act as the enterprise (service account). Find in: Box Admin Console > Enterprise Settings.", "examples": [ "12345678" ] }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "User ID to authenticate as. Used when the app needs to act as a specific managed user. Mutually exclusive with enterprise_id for token acquisition.", "examples": [ "87654321" ] } }, "type": "object", "required": [ "client_id", "client_secret" ], "title": "BoxCCGCredentials", "description": "Credentials for Box Client Credentials Grant (CCG) authentication.\n\nCCG provides server-to-server authentication without user interaction.\nRecommended for enterprise and automated sync operations.\n\nPrerequisites:\n - Create a Box application with Server Authentication (Client Credentials Grant)\n - Authorize the application in the Box Admin Console\n - Optionally configure an enterprise or user ID to act as\n\nSecurity:\n - client_secret encrypted at rest via CSFLE\n - No user tokens involved; app authenticates as itself or as a user/enterprise" }, "BoxConfig": { "properties": { "provider_type": { "type": "string", "const": "box", "title": "Provider Type", "default": "box" }, "credentials": { "oneOf": [ { "$ref": "#/components/schemas/BoxOAuthCredentials" }, { "$ref": "#/components/schemas/BoxCCGCredentials" }, { "$ref": "#/components/schemas/BoxJWTCredentials" } ], "title": "Credentials", "description": "REQUIRED. Box authentication credentials. Choose 'oauth' for user-level access, 'ccg' for server-to-server (recommended), or 'jwt' for high-security enterprise. The 'type' field determines which authentication flow is used.", "discriminator": { "propertyName": "type", "mapping": { "ccg": "#/components/schemas/BoxCCGCredentials", "jwt": "#/components/schemas/BoxJWTCredentials", "oauth": "#/components/schemas/BoxOAuthCredentials" } } }, "folder_id": { "type": "string", "title": "Folder Id", "description": "Box folder ID to sync from. Default '0' is the root folder. Find folder ID: Open folder in Box web UI, copy the numeric ID from the URL. Example URL: https://app.box.com/folder/123456789 \u2192 folder_id='123456789'", "default": "0", "examples": [ "0", "123456789", "987654321" ] } }, "type": "object", "required": [ "credentials" ], "title": "BoxConfig", "description": "Box cloud content management and file sharing configuration.\n\nEnables Mixpeek to connect to Box for automated file ingestion and\nsynchronization. Supports enterprise-grade content management features\nincluding folder sync, metadata, versioning, and retention policies.\n\nAuthentication Methods:\n 1. OAuth 2.0 (for user-level access):\n - Standard OAuth flow with access/refresh tokens\n - Access scoped to the authorizing user's content\n\n 2. Client Credentials Grant (CCG) (RECOMMENDED for production):\n - Server-to-server without user interaction\n - Acts as service account or specific user\n - Requires admin authorization in Box Admin Console\n\n 3. JWT (for high-security enterprise):\n - RSA key pair for signing JWT assertions\n - No user interaction required\n - Highest security option\n\nRequirements:\n - Box Developer account with an application\n - Application authorized in Box Admin Console (for CCG/JWT)\n - Network connectivity to api.box.com\n\nUse Cases:\n - Sync enterprise document libraries\n - Ingest compliance and legal documents\n - Monitor collaboration folders for new content\n - Archive and search enterprise content", "examples": [ { "credentials": { "client_id": "abc123def456", "client_secret": "your-client-secret", "enterprise_id": "12345678", "type": "ccg" }, "description": "Box with Client Credentials Grant (recommended)", "folder_id": "0", "provider_type": "box" }, { "credentials": { "access_token": "your-access-token", "client_id": "abc123def456", "client_secret": "your-client-secret", "refresh_token": "your-refresh-token", "type": "oauth" }, "description": "Box with OAuth 2.0 user authentication", "folder_id": "987654321", "provider_type": "box" }, { "credentials": { "client_id": "abc123def456", "client_secret": "your-client-secret", "enterprise_id": "12345678", "jwt_key_id": "abcdef12", "private_key": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END ENCRYPTED PRIVATE KEY-----\n", "private_key_passphrase": "passphrase", "type": "jwt" }, "description": "Box with JWT authentication", "folder_id": "0", "provider_type": "box" } ] }, "BoxJWTCredentials": { "properties": { "type": { "type": "string", "const": "jwt", "title": "Type", "default": "jwt" }, "client_id": { "type": "string", "title": "Client Id", "description": "REQUIRED. Box application client ID.", "examples": [ "abc123def456ghi789" ] }, "client_secret": { "type": "string", "title": "Client Secret", "description": "REQUIRED. Box application client secret. SECURITY: Encrypted at rest via CSFLE." }, "enterprise_id": { "type": "string", "title": "Enterprise Id", "description": "REQUIRED. Box enterprise ID for JWT authentication. Find in: Box Admin Console > Enterprise Settings.", "examples": [ "12345678" ] }, "jwt_key_id": { "type": "string", "title": "Jwt Key Id", "description": "REQUIRED. Public key ID registered with Box. Found in the JSON config file as 'publicKeyID'.", "examples": [ "abcdef12" ] }, "private_key": { "type": "string", "title": "Private Key", "description": "REQUIRED. PEM-encoded RSA private key for JWT signing. SECURITY: Encrypted at rest via CSFLE. Never log or expose. Found in the JSON config file as 'privateKey'." }, "private_key_passphrase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Private Key Passphrase", "description": "Passphrase for the private key if it is encrypted. SECURITY: Encrypted at rest via CSFLE." } }, "type": "object", "required": [ "client_id", "client_secret", "enterprise_id", "jwt_key_id", "private_key" ], "title": "BoxJWTCredentials", "description": "Credentials for Box JWT (JSON Web Token) authentication.\n\nJWT provides server-to-server authentication using a public/private key pair.\nRecommended for enterprise integrations requiring high security.\n\nPrerequisites:\n - Create a Box application with Server Authentication (with JWT)\n - Generate a public/private key pair in the Developer Console\n - Authorize the application in the Box Admin Console\n - Download the JSON configuration file\n\nSecurity:\n - private_key encrypted at rest via CSFLE\n - RSA key pair used for signing JWT assertions\n - No user interaction required" }, "BoxOAuthCredentials": { "properties": { "type": { "type": "string", "const": "oauth", "title": "Type", "default": "oauth" }, "client_id": { "type": "string", "title": "Client Id", "description": "REQUIRED. Box application client ID. Found in: Box Developer Console > Your App > Configuration > OAuth 2.0 Credentials.", "examples": [ "abc123def456ghi789" ] }, "client_secret": { "type": "string", "title": "Client Secret", "description": "REQUIRED. Box application client secret. SECURITY: Encrypted at rest via CSFLE. Never log or expose. Found in: Box Developer Console > Your App > Configuration." }, "access_token": { "type": "string", "title": "Access Token", "description": "REQUIRED. Box OAuth 2.0 access token. SECURITY: Encrypted at rest. Expires in ~60 minutes." }, "refresh_token": { "type": "string", "title": "Refresh Token", "description": "REQUIRED. Box OAuth 2.0 refresh token for automatic token renewal. SECURITY: Encrypted at rest. Single-use; new one issued on each refresh." } }, "type": "object", "required": [ "client_id", "client_secret", "access_token", "refresh_token" ], "title": "BoxOAuthCredentials", "description": "Credentials for Box OAuth 2.0 authentication.\n\nBox supports OAuth 2.0 with access and refresh tokens. The refresh token\nis used to automatically obtain new access tokens without user interaction.\n\nPrerequisites:\n - Create a Box application at https://developer.box.com\n - Configure OAuth 2.0 with the appropriate scopes\n - Complete the OAuth consent flow to obtain tokens\n\nSecurity:\n - client_secret, access_token, and refresh_token encrypted at rest via CSFLE\n - Access tokens expire in ~60 minutes; refresh tokens used for renewal\n - Token refresh happens automatically during sync execution" }, "BrightDataConfig": { "properties": { "provider_type": { "type": "string", "const": "brightdata", "title": "Provider Type", "default": "brightdata" }, "credentials": { "$ref": "#/components/schemas/BrightDataCredentials", "description": "REQUIRED. BrightData API token credentials." }, "customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Id", "description": "NOT REQUIRED. BrightData customer ID (zone-level auth). Required when using zone-specific API access. Find in: BrightData Dashboard > your zone settings.", "examples": [ "hl_abc12345" ] }, "default_output_format": { "type": "string", "enum": [ "jsonl", "json", "csv", "ndjson" ], "title": "Default Output Format", "description": "Output format for downloaded dataset results. 'jsonl' (default) streams one JSON object per line. 'json' returns a full JSON array. 'csv' returns comma-separated values. 'ndjson' is equivalent to jsonl.", "default": "jsonl" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "NOT REQUIRED. ISO 3166-1 alpha-2 country code for geo-targeted data collection. When set, the dataset snapshot targets data from this country. Examples: 'us', 'gb', 'de', 'jp'.", "examples": [ "us", "gb", "de" ] }, "inputs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Inputs", "description": "NOT REQUIRED. Default seed inputs for datasets that require input URLs or records (e.g. LinkedIn company profiles). Each item is a JSON object passed to the BrightData trigger API. Overridden per-call when inputs are supplied at sync time.", "examples": [ [ { "url": "https://www.linkedin.com/company/google" } ] ] } }, "type": "object", "required": [ "credentials" ], "title": "BrightDataConfig", "description": "BrightData web data platform configuration for dataset and scraper syncs.\n\nEnables Mixpeek to collect data from BrightData's pre-built datasets\n(LinkedIn, Amazon, Google Maps, etc.) or custom web scrapers. Each sync\ntriggers a new dataset snapshot, polls until ready, then downloads and\ningests each row as a bucket object.\n\nAuthentication:\n - API token from BrightData dashboard\n\nRequirements:\n - Active BrightData subscription with Datasets or Web Scraper access\n - API token with appropriate dataset permissions\n - Network connectivity to api.brightdata.com\n\nUse Cases:\n - Ingest LinkedIn company/people datasets for lead generation\n - Monitor e-commerce pricing via Amazon product datasets\n - Collect Google Maps business data for location intelligence\n - Run custom web scrapers and process results as documents\n - Aggregate public social media data for trend analysis", "examples": [ { "credentials": { "api_token": "your-brightdata-api-token", "type": "api_token" }, "default_output_format": "jsonl", "description": "BrightData dataset sync", "provider_type": "brightdata" }, { "country": "us", "credentials": { "api_token": "your-brightdata-api-token", "type": "api_token" }, "customer_id": "hl_abc12345", "default_output_format": "jsonl", "description": "BrightData with geo-targeting", "provider_type": "brightdata" } ] }, "BrightDataCredentials": { "properties": { "type": { "type": "string", "const": "api_token", "title": "Type", "default": "api_token" }, "api_token": { "type": "string", "title": "Api Token", "description": "REQUIRED. BrightData API token. SECURITY: Encrypted at rest. Never log or expose. Find in: BrightData Dashboard > Account > API Token.", "examples": [ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] } }, "type": "object", "required": [ "api_token" ], "title": "BrightDataCredentials", "description": "API token credentials for BrightData platform.\n\nSecurity:\n - api_token is encrypted at rest via CSFLE\n - Tokens can be created/rotated in the BrightData dashboard" }, "BucketCreateRequest": { "properties": { "bucket_name": { "type": "string", "title": "Bucket Name", "description": "Human-readable name for the bucket" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the bucket" }, "bucket_schema": { "$ref": "#/components/schemas/BucketSchema-Input", "description": "REQUIRED. Schema definition for objects in this bucket. Must include a 'properties' object mapping field names to type definitions. Use Mixpeek types (string, text, image, video, etc.) \u2014 NOT JSON Schema types like 'keyword'. Example: {\"properties\": {\"title\": {\"type\": \"string\"}, \"photo\": {\"type\": \"image\"}}}" }, "unique_key": { "anyOf": [ { "$ref": "#/components/schemas/UniqueKeyConfig" }, { "type": "null" } ], "description": "Unique key configuration for this bucket (OPTIONAL). Enables uniqueness enforcement and upsert operations on specified field(s) from the schema. Cannot be changed after bucket creation." }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional metadata for the bucket" }, "storage_class": { "anyOf": [ { "$ref": "#/components/schemas/StorageClass" }, { "type": "null" } ], "description": "OPTIONAL object-storage tier for this bucket's objects: standard | nearline | coldline | archive (provider-agnostic). NOTE: applied on write for sync-based ingestion (the primary media path); tiering for direct uploads (POST /objects) and presigned uploads, plus retroactive re-tiering of existing objects, are in progress (TG-2837). Omit for the provider default (standard)." } }, "type": "object", "required": [ "bucket_name", "bucket_schema" ], "title": "BucketCreateRequest", "description": "Request model for creating a new bucket.\n\nREQUIRED: A bucket_schema must be defined to enable data processing and validation.\n\nThe bucket_schema tells the system what fields your objects will have, enabling:\n- Collections to map your data fields to feature extractors via input_mappings\n- Validation of object structure at upload time\n- Type-safe data pipelines from bucket \u2192 collection \u2192 retrieval\n\nEvery bucket must have a schema that defines the structure of objects it will contain.", "examples": [ { "bucket_name": "product_images", "bucket_schema": { "properties": { "image": { "description": "Product image blob", "type": "image" }, "metadata": { "description": "Product information", "properties": { "title": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "float" } }, "type": "object" } } }, "description": "Product images with metadata for e-commerce", "metadata": { "department": "Sales", "region": "US" } }, { "bucket_name": "video_content", "bucket_schema": { "properties": { "video": { "description": "Main video file", "type": "video" }, "transcript": { "description": "Video transcript text", "type": "text" }, "thumbnail": { "description": "Video thumbnail", "type": "image" }, "metadata": { "properties": { "duration_seconds": { "type": "integer" }, "title": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Video files with transcripts and thumbnails", "metadata": { "content_type": "educational" } }, { "bucket_name": "text_documents", "bucket_schema": { "properties": { "content": { "description": "Main text content", "type": "text" }, "metadata": { "properties": { "title": { "type": "string" }, "author": { "type": "string" }, "published_date": { "type": "datetime" } }, "type": "object" } } }, "description": "Text documents for NLP processing" } ] }, "BucketHealthResponse": { "properties": { "bucket_id": { "type": "string", "title": "Bucket Id", "description": "Bucket identifier" }, "time_range": { "$ref": "#/components/schemas/api__analytics__buckets__models__TimeRange", "description": "Query time range" }, "overall_health": { "type": "string", "title": "Overall Health", "description": "Overall health status" }, "total_errors": { "type": "integer", "title": "Total Errors", "description": "Total error count" }, "error_breakdown": { "items": { "$ref": "#/components/schemas/ErrorBreakdown" }, "type": "array", "title": "Error Breakdown", "description": "Errors by type" }, "sync_health": { "items": { "$ref": "#/components/schemas/SyncHealthMetric" }, "type": "array", "title": "Sync Health", "description": "Sync health per config" }, "stuck_syncs": { "items": { "type": "string" }, "type": "array", "title": "Stuck Syncs", "description": "Sync configs with no recent activity" } }, "type": "object", "required": [ "bucket_id", "time_range", "overall_health", "total_errors", "error_breakdown", "sync_health", "stuck_syncs" ], "title": "BucketHealthResponse", "description": "Bucket health monitoring response." }, "BucketListStats": { "properties": { "total_objects": { "type": "integer", "title": "Total Objects", "description": "Total number of objects across all buckets", "default": 0 }, "total_size_bytes": { "type": "integer", "title": "Total Size Bytes", "description": "Total size in bytes across all buckets", "default": 0 }, "avg_objects_per_bucket": { "type": "number", "title": "Avg Objects Per Bucket", "description": "Average number of objects per bucket", "default": 0.0 }, "avg_size_per_bucket": { "type": "number", "title": "Avg Size Per Bucket", "description": "Average size in bytes per bucket", "default": 0.0 } }, "type": "object", "title": "BucketListStats", "description": "Aggregate statistics for a list of buckets." }, "BucketPatchRequest": { "properties": { "bucket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Name", "description": "Human-readable name for the bucket" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the bucket" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata for the bucket" }, "bucket_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Input" }, { "type": "null" } ], "description": "Schema definition for objects in this bucket" }, "source_adapter": { "anyOf": [ { "$ref": "#/components/schemas/SourceAdapterConfig" }, { "type": "null" } ], "description": "Source adapter configuration for inbound webhook-driven ingestion" } }, "type": "object", "title": "BucketPatchRequest", "description": "Request model for partial update of an existing bucket (PATCH operation)." }, "BucketResponse": { "properties": { "bucket_id": { "type": "string", "title": "Bucket Id", "description": "Unique identifier for the bucket" }, "bucket_name": { "type": "string", "title": "Bucket Name", "description": "Human-readable name for the bucket" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the bucket" }, "bucket_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Output" }, { "type": "null" } ], "description": "Schema definition for objects in this bucket" }, "unique_key": { "anyOf": [ { "$ref": "#/components/schemas/UniqueKeyConfig" }, { "type": "null" } ], "description": "Unique key configuration for this bucket (if configured)" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional metadata for the bucket" }, "storage_class": { "anyOf": [ { "$ref": "#/components/schemas/StorageClass" }, { "type": "null" } ], "description": "Object-storage tier for this bucket's objects: standard | nearline | coldline | archive. Provider-agnostic (GCS STANDARD/NEARLINE/COLDLINE/ARCHIVE; S3/MinIO STANDARD/STANDARD_IA/GLACIER). NOTE: applied on write for sync-based ingestion (the primary media path); tiering for direct/presigned uploads and retroactive re-tiering of existing objects are in progress (TG-2837). None = provider default." }, "object_count": { "type": "integer", "title": "Object Count", "description": "Number of objects in the bucket" }, "total_size_bytes": { "type": "integer", "title": "Total Size Bytes", "description": "Total size of all objects in the bucket in bytes" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "When the bucket was created" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last modification time of bucket metadata" }, "last_upload_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Upload At", "description": "When the last object was uploaded to this bucket" }, "stats_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Stats Updated At", "description": "When bucket stats were last successfully recalculated" }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "Bucket lifecycle status (ACTIVE, ARCHIVED, SUSPENDED, IN_PROGRESS for deleting)", "default": "ACTIVE" }, "is_locked": { "type": "boolean", "title": "Is Locked", "description": "Whether the bucket is locked (read-only)", "default": false }, "batch_stats": { "anyOf": [ { "$ref": "#/components/schemas/BatchStatistics" }, { "type": "null" } ], "description": "Batch statistics for this bucket (calculated asynchronously, stored in DB)" }, "storage_stats": { "anyOf": [ { "$ref": "#/components/schemas/StorageStatistics" }, { "type": "null" } ], "description": "Storage statistics for this bucket (calculated asynchronously, stored in DB)" }, "source_adapter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Adapter", "description": "Source adapter configuration for inbound webhook-driven ingestion" } }, "type": "object", "required": [ "bucket_name", "object_count", "total_size_bytes" ], "title": "BucketResponse", "description": "Response model for bucket operations." }, "BucketSchema-Input": { "properties": { "properties": { "additionalProperties": { "$ref": "#/components/schemas/BucketSchemaField-Input" }, "type": "object", "title": "Properties", "description": "REQUIRED. Map of field names to their type definitions. Each field must have a 'type' from the supported types: metadata types (string, number, integer, float, boolean, object, array, date, datetime) or file/blob types (text, image, audio, video, pdf, excel). NOTE: Use Mixpeek types, NOT JSON Schema types \u2014 e.g. use 'string' not 'keyword', 'text' for text blobs, 'image' for image blobs. Example: {\"title\": {\"type\": \"string\"}, \"photo\": {\"type\": \"image\"}}" } }, "additionalProperties": true, "type": "object", "required": [ "properties" ], "title": "BucketSchema", "description": "Schema definition for bucket objects.\n\nIMPORTANT: The bucket schema defines what fields your bucket objects will have.\nThis schema is REQUIRED if you want to:\n1. Create collections that use input_mappings to process your bucket data\n2. Validate object structure before ingestion\n3. Enable type-safe data pipelines\n\nThe schema defines the custom fields that will be used in:\n- Blob properties (e.g., \"content\", \"thumbnail\", \"transcript\")\n- Object metadata structure\n- Blob data structures\n\nExample workflow:\n1. Create bucket WITH schema defining your data structure\n2. Upload objects that conform to that schema\n3. Create collections that map schema fields to feature extractors\n\nWithout a bucket_schema, collections cannot use input_mappings." }, "BucketSchema-Output": { "properties": { "properties": { "additionalProperties": { "$ref": "#/components/schemas/BucketSchemaField-Output" }, "type": "object", "title": "Properties", "description": "REQUIRED. Map of field names to their type definitions. Each field must have a 'type' from the supported types: metadata types (string, number, integer, float, boolean, object, array, date, datetime) or file/blob types (text, image, audio, video, pdf, excel). NOTE: Use Mixpeek types, NOT JSON Schema types \u2014 e.g. use 'string' not 'keyword', 'text' for text blobs, 'image' for image blobs. Example: {\"title\": {\"type\": \"string\"}, \"photo\": {\"type\": \"image\"}}" } }, "additionalProperties": true, "type": "object", "required": [ "properties" ], "title": "BucketSchema", "description": "Schema definition for bucket objects.\n\nIMPORTANT: The bucket schema defines what fields your bucket objects will have.\nThis schema is REQUIRED if you want to:\n1. Create collections that use input_mappings to process your bucket data\n2. Validate object structure before ingestion\n3. Enable type-safe data pipelines\n\nThe schema defines the custom fields that will be used in:\n- Blob properties (e.g., \"content\", \"thumbnail\", \"transcript\")\n- Object metadata structure\n- Blob data structures\n\nExample workflow:\n1. Create bucket WITH schema defining your data structure\n2. Upload objects that conform to that schema\n3. Create collections that map schema fields to feature extractors\n\nWithout a bucket_schema, collections cannot use input_mappings." }, "BucketSchemaField-Input": { "properties": { "type": { "$ref": "#/components/schemas/BucketSchemaFieldType" }, "default": { "anyOf": [ {}, { "type": "null" } ], "title": "Default" }, "items": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchemaField-Input" }, { "type": "null" } ] }, "properties": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/BucketSchemaField-Input" }, "type": "object" }, { "type": "null" } ], "title": "Properties" }, "examples": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enum": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Enum" }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Required", "default": false } }, "additionalProperties": true, "type": "object", "required": [ "type" ], "title": "BucketSchemaField", "description": "Schema field definition for bucket objects." }, "BucketSchemaField-Output": { "properties": { "type": { "$ref": "#/components/schemas/BucketSchemaFieldType" }, "default": { "anyOf": [ {}, { "type": "null" } ], "title": "Default" }, "items": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchemaField-Output" }, { "type": "null" } ] }, "properties": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/BucketSchemaField-Output" }, "type": "object" }, { "type": "null" } ], "title": "Properties" }, "examples": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enum": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Enum" }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Required", "default": false } }, "additionalProperties": true, "type": "object", "required": [ "type" ], "title": "BucketSchemaField", "description": "Schema field definition for bucket objects." }, "BucketSchemaFieldType": { "type": "string", "enum": [ "string", "number", "integer", "float", "boolean", "object", "array", "date", "datetime", "text", "image", "audio", "video", "pdf", "excel" ], "title": "BucketSchemaFieldType", "description": "Supported data types for bucket schema fields.\n\nTypes fall into two categories:\n\n1. **Metadata Types** (JSON types):\n - Stored as object metadata\n - Standard JSON-compatible types\n - Not processed by extractors (unless explicitly mapped)\n - Examples: string, number, boolean, date\n\n2. **File Types** (blobs):\n - Stored as files/blobs\n - Processed by extractors\n - Require file content (URL or base64)\n - Examples: text, image, video, pdf\n\n**GIF Special Handling**:\n GIF files can be declared as either IMAGE or VIDEO type:\n\n - As IMAGE: GIF is embedded as a single static image (first frame)\n - As VIDEO: GIF is decomposed frame-by-frame with embeddings per frame\n\n The multimodal extractor detects GIFs via MIME type (image/gif) and routes\n them based on your schema declaration. Use VIDEO for animated GIFs where\n frame-level search is needed, IMAGE for static/thumbnail use cases.\n\nNOTE: For retriever input schemas that need to accept document references\n(e.g., \"find similar documents\"), use RetrieverInputSchemaFieldType instead,\nwhich includes all bucket types plus document_reference." }, "BucketStorageResponse": { "properties": { "bucket_id": { "type": "string", "title": "Bucket Id", "description": "Bucket identifier" }, "time_range": { "$ref": "#/components/schemas/api__analytics__buckets__models__TimeRange", "description": "Query time range" }, "metrics": { "items": { "$ref": "#/components/schemas/StorageMetric" }, "type": "array", "title": "Metrics", "description": "Time-series storage metrics" }, "summary": { "additionalProperties": true, "type": "object", "title": "Summary", "description": "Summary statistics" } }, "type": "object", "required": [ "bucket_id", "time_range", "metrics" ], "title": "BucketStorageResponse", "description": "Storage growth trends response." }, "BucketUpdateRequest": { "properties": { "bucket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bucket Name", "description": "Human-readable name for the bucket" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the bucket" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata for the bucket" }, "bucket_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Input" }, { "type": "null" } ], "description": "Schema definition for objects in this bucket" }, "storage_class": { "anyOf": [ { "$ref": "#/components/schemas/StorageClass" }, { "type": "null" } ], "description": "Object-storage tier: standard | nearline | coldline | archive. NOTE: applied on write for sync-based ingestion (the primary media path); tiering for direct uploads (POST /objects) and presigned uploads, plus retroactive re-tiering of existing objects, are in progress (TG-2837)." } }, "type": "object", "title": "BucketUpdateRequest", "description": "Request model for updating an existing bucket." }, "BucketUsageResponse": { "properties": { "bucket_id": { "type": "string", "title": "Bucket Id", "description": "Bucket identifier" }, "time_range": { "$ref": "#/components/schemas/api__analytics__buckets__models__TimeRange", "description": "Query time range" }, "metrics": { "items": { "$ref": "#/components/schemas/UsageMetric" }, "type": "array", "title": "Metrics", "description": "Usage metrics" }, "cost_breakdown": { "$ref": "#/components/schemas/CostBreakdown", "description": "Cost breakdown" }, "total_credits": { "type": "integer", "title": "Total Credits", "description": "Total credits consumed" }, "total_cost_usd": { "type": "number", "title": "Total Cost Usd", "description": "Total cost in USD" } }, "type": "object", "required": [ "bucket_id", "time_range", "metrics", "cost_breakdown", "total_credits", "total_cost_usd" ], "title": "BucketUsageResponse", "description": "Bucket usage and cost analytics response." }, "BudgetLimits": { "properties": { "max_credits": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Max Credits", "description": "Maximum credits allowed for a single execution (OPTIONAL)." }, "max_time_ms": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Max Time Ms", "description": "Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL)." } }, "type": "object", "title": "BudgetLimits", "description": "User-defined limits for time and credits during execution.", "examples": [ { "max_credits": 100.0, "max_time_ms": 60000 }, { "max_time_ms": 120000 } ] }, "BuildConfig": { "properties": { "entry": { "type": "string", "title": "Entry", "description": "Build entry point", "default": "src/layout.jsx" }, "framework": { "type": "string", "const": "react", "title": "Framework", "default": "react" }, "tailwind": { "type": "boolean", "title": "Tailwind", "default": true }, "env_vars": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Env Vars", "description": "Build-time environment variables injected into the app. Set MIXPEEK_API_KEY here to enable the /_api server-side proxy \u2014 without it the proxy falls back to the canvas server's default key. NOTE: every key here EXCEPT MIXPEEK_API_KEY is injected into the browser's window.__MIXPEEK__. For third-party secrets that must stay server-side (e.g. SERPAPI_KEY for a /functions/* handler), use ``secrets`` below, not ``env_vars``." }, "secrets": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Secrets", "description": "Server-only secrets for the app's /functions/* server-side handlers, exposed to them as ``ctx.env``. NEVER injected into the browser window.__MIXPEEK__ and masked ('***') in API responses. Use for third-party API keys (e.g. SERPAPI_KEY)." }, "asset_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Prefix", "description": "CDN asset prefix once deployed" } }, "type": "object", "title": "BuildConfig", "description": "JSX build configuration for an App.\n\nPhase 1: schema only. Phase 3: used by the build pipeline Celery task." }, "BulkAnnotationCreate": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Document to annotate." }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "label": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Label" }, "confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence" }, "reasoning": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Reasoning" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload" }, "retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retriever Id" }, "execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Id" }, "stage_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage Name" } }, "type": "object", "required": [ "document_id", "label" ], "title": "BulkAnnotationCreate", "description": "Single create within a bulk request." }, "BulkAnnotationResult": { "properties": { "annotation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Annotation Id", "description": "Annotation ID (set for create/update)." }, "operation": { "type": "string", "title": "Operation", "description": "Operation type: create, update, or delete." }, "success": { "type": "boolean", "title": "Success", "description": "Whether the operation succeeded." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if failed." } }, "type": "object", "required": [ "operation", "success" ], "title": "BulkAnnotationResult", "description": "Result of a single operation within a bulk request." }, "BulkAnnotationUpdate": { "properties": { "annotation_id": { "type": "string", "title": "Annotation Id", "description": "Annotation to update." }, "label": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Label" }, "confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence" }, "reasoning": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Reasoning" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload" } }, "type": "object", "required": [ "annotation_id" ], "title": "BulkAnnotationUpdate", "description": "Single update within a bulk request." }, "BulkAnnotationsRequest": { "properties": { "create": { "items": { "$ref": "#/components/schemas/BulkAnnotationCreate" }, "type": "array", "maxItems": 1000, "title": "Create", "description": "Annotations to create." }, "update": { "items": { "$ref": "#/components/schemas/BulkAnnotationUpdate" }, "type": "array", "maxItems": 1000, "title": "Update", "description": "Annotations to update." }, "delete": { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "title": "Delete", "description": "Annotation IDs to delete." } }, "type": "object", "title": "BulkAnnotationsRequest", "description": "Bulk create, update, and/or delete annotations in a single call.\n\nProvide any combination of creates, updates, and deletes. Each operation\nis independent \u2014 a failure in one does not roll back the others." }, "BulkAnnotationsResponse": { "properties": { "created_count": { "type": "integer", "title": "Created Count", "default": 0 }, "updated_count": { "type": "integer", "title": "Updated Count", "default": 0 }, "deleted_count": { "type": "integer", "title": "Deleted Count", "default": 0 }, "failed_count": { "type": "integer", "title": "Failed Count", "default": 0 }, "results": { "items": { "$ref": "#/components/schemas/BulkAnnotationResult" }, "type": "array", "title": "Results" } }, "type": "object", "title": "BulkAnnotationsResponse", "description": "Response for bulk annotation operations." }, "BulkInteractionItemResult": { "properties": { "index": { "type": "integer", "title": "Index", "description": "0-based index of this item in the request." }, "interaction_id": { "type": "string", "title": "Interaction Id", "description": "Assigned interaction ID." }, "status": { "type": "string", "title": "Status", "description": "Item status: 'created' or 'failed'.", "default": "created" } }, "type": "object", "required": [ "index", "interaction_id" ], "title": "BulkInteractionItemResult", "description": "Per-item result from a bulk interaction write." }, "BulkInteractionsRequest": { "properties": { "interactions": { "items": { "$ref": "#/components/schemas/SearchInteraction" }, "type": "array", "maxItems": 1000, "minItems": 1, "title": "Interactions", "description": "Interactions to record (1-1000). For historical backfill, set each interaction's `occurred_at` to its true time." } }, "type": "object", "required": [ "interactions" ], "title": "BulkInteractionsRequest", "description": "Record many interactions in one call \u2014 for backfilling historical logs.\n\nThe intended use is migrating an existing click/purchase history into\nMixpeek: send the interactions in chunks (\u2264 1000 per call) with each one's\n``occurred_at`` set to its true timestamp, so learned-fusion temporal decay\nweights them correctly. Backfilled events bypass the real-time session cache." }, "BulkInteractionsResponse": { "properties": { "created": { "type": "integer", "title": "Created", "description": "Number of interactions accepted for write." }, "failed": { "type": "integer", "title": "Failed", "description": "Number that could not be processed (see errors).", "default": 0 }, "errors": { "items": { "type": "string" }, "type": "array", "title": "Errors", "description": "Per-interaction error messages (indexed), if any failed." }, "results": { "items": { "$ref": "#/components/schemas/BulkInteractionItemResult" }, "type": "array", "title": "Results", "description": "Per-item results with assigned interaction IDs." } }, "type": "object", "required": [ "created" ], "title": "BulkInteractionsResponse", "description": "Result of a bulk interaction write." }, "BulkMarkDLQRequest": { "properties": { "error_types": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Error Types", "description": "Error type names to mark as permanently failed, e.g. ['NotFoundError', 'ValidationError']." } }, "type": "object", "required": [ "error_types" ], "title": "BulkMarkDLQRequest", "description": "Request to mark DLQ entries as permanently failed by error type." }, "BulkMarkDLQResponse": { "properties": { "updated": { "type": "integer", "title": "Updated", "description": "Number of DLQ entries marked as permanently failed." } }, "type": "object", "required": [ "updated" ], "title": "BulkMarkDLQResponse", "description": "Response from bulk-marking DLQ entries as permanently failed." }, "BulkRequeueDLQRequest": { "properties": { "error_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Error Types", "description": "Optional error-type filter, e.g. ['S3StorageError', 'TimeoutError']. Omit to requeue every exhausted entry for the sync config. Entries that have not exhausted their retries are never touched \u2014 they are already retrying." } }, "type": "object", "title": "BulkRequeueDLQRequest", "description": "Request to requeue exhausted DLQ entries back into the retry path (TG-2999)." }, "BulkRequeueDLQResponse": { "properties": { "requeued": { "type": "integer", "title": "Requeued", "description": "Number of DLQ entries returned to the retry path." } }, "type": "object", "required": [ "requeued" ], "title": "BulkRequeueDLQResponse", "description": "Response from requeuing DLQ entries." }, "BulkSoftDeleteRequest": { "properties": { "object_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 5000, "minItems": 1, "title": "Object Ids", "description": "Object IDs to soft-delete (max 5000 per request). Records are retained and flipped to a non-active lifecycle state so retrieval excludes them; reversible by clearing the marker." }, "reason": { "type": "string", "maxLength": 500, "title": "Reason", "description": "Why these objects are being soft-deleted (audit trail)." }, "lifecycle_state": { "type": "string", "title": "Lifecycle State", "description": "Lifecycle state to flip to (default 'disabled').", "default": "disabled" }, "source": { "type": "string", "title": "Source", "description": "Marker source tag (default 'bulk_purge').", "default": "bulk_purge" } }, "type": "object", "required": [ "object_ids", "reason" ], "title": "BulkSoftDeleteRequest", "description": "Request model for bulk soft-deleting objects by id (recoverable purge).", "examples": [ { "object_ids": [ "obj_abc123", "obj_def456" ], "reason": "scope footage bucket to 8 target brands" } ] }, "BulkSoftDeleteResponse": { "properties": { "soft_deleted": { "type": "integer", "title": "Soft Deleted", "description": "Number of object records flipped." }, "requested": { "type": "integer", "title": "Requested", "description": "Number of object IDs requested." }, "collections": { "type": "integer", "title": "Collections", "description": "Collections sourced from the bucket considered for propagation." } }, "type": "object", "required": [ "soft_deleted", "requested", "collections" ], "title": "BulkSoftDeleteResponse", "description": "Response for a bulk soft-delete operation." }, "BulkSubmitBatchesRequest": { "properties": { "collection_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Collection Ids", "description": "Collections to process. Omit to auto-discover all collections sourced from this bucket (plus downstream dependencies)." }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "Optional filter to scope which objects are submitted. Omit to submit EVERY object in the bucket (the whole-bucket case)." }, "chunk_size": { "type": "integer", "maximum": 50000.0, "minimum": 1.0, "title": "Chunk Size", "description": "Objects per batch. Clamped down to your tier's max_batch_size. Default 1000 \u2014 a good balance of parallelism and per-batch overhead. Sizing model: each batch runs as its own job whose workers scale at ~1 CPU worker per 500 objects up to a per-job worker ceiling, so 16k-20k objects saturates one job's parallelism \u2014 for large corpora (100k+ objects) prefer chunk_size 20000. Larger chunks don't run faster; they only raise the cost of a mid-run failure (progress is still resumable per-object via the processing ledger). Much smaller chunks pay one cluster cold-start each and queue behind your tier's concurrent-batch limit. Full guide: docs.mixpeek.com/operations/batch-ingestion-at-scale.", "default": 1000 }, "dedup_strategy": { "$ref": "#/components/schemas/DedupStrategy", "description": "How already-processed objects are handled (skip/replace/force).", "default": "skip" }, "max_objects": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Objects", "description": "Optional cap on total objects streamed (safety bound for very large buckets). Omit to submit the whole bucket." } }, "type": "object", "title": "BulkSubmitBatchesRequest", "description": "Submit a WHOLE bucket as N auto-chunked, auto-queued batches in one call.\n\nThe server streams the bucket's objects (paginated), de-duplicates them,\nchunks them into ``chunk_size``-object batches, and submits each \u2014 so the\nclient makes ONE call instead of a paced chunk-loop. This kills the\nclient-side cursor-overlap (409 storm), the 5k object-count timeout, and the\nno-whole-bucket frustration at once (BACKE-1121 phase 4). Each batch is\naccepted and QUEUED (accept-and-queue admission); poll the returned\n``batch_group_id`` / batch ids for QUEUED -> PROCESSING." }, "BulkSubmitBatchesResponse": { "properties": { "batch_group_id": { "type": "string", "title": "Batch Group Id", "description": "Correlates all batches created by this call." }, "total_objects": { "type": "integer", "title": "Total Objects", "description": "Distinct objects streamed (post-dedup)." }, "total_batches": { "type": "integer", "title": "Total Batches", "description": "Batches created." }, "submitted": { "type": "integer", "title": "Submitted", "description": "Batches accepted/queued successfully." }, "failed": { "type": "integer", "title": "Failed", "description": "Batches that failed admission/submit." }, "chunk_size": { "type": "integer", "title": "Chunk Size", "description": "Effective per-batch object count used." }, "batches": { "items": { "$ref": "#/components/schemas/BulkSubmittedBatch" }, "type": "array", "title": "Batches", "description": "Per-batch results with status + queue position." } }, "type": "object", "required": [ "batch_group_id", "total_objects", "total_batches", "submitted", "failed", "chunk_size", "batches" ], "title": "BulkSubmitBatchesResponse", "description": "Result of a whole-bucket bulk submit." }, "BulkSubmittedBatch": { "properties": { "batch_id": { "type": "string", "title": "Batch Id" }, "status": { "type": "string", "title": "Status" }, "object_count": { "type": "integer", "title": "Object Count" }, "queue_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Queue Position" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "batch_id", "status", "object_count" ], "title": "BulkSubmittedBatch", "description": "One batch in a bulk-submit group." }, "BulkUpdateDocumentsRequest": { "properties": { "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "OPTIONAL. Filter conditions to match documents for update. If not provided, updates ALL documents in the collection. Uses the logical AND/OR/NOT shape \u2014 a list of {field, operator, value} conditions (operators: eq, ne, in, nin, gt, gte, lt, lte, contains, exists, \u2026). The MVS-native {'must': [{'key': ...}]} shape is NOT accepted here. Example: {'AND': [{'field': 'metadata.status', 'operator': 'eq', 'value': 'pending'}]}", "examples": [ { "AND": [ { "field": "metadata.status", "operator": "eq", "value": "pending" } ] }, { "AND": [ { "field": "metadata.created_at", "operator": "gt", "value": "2024-01-01" } ] } ] }, "update_data": { "additionalProperties": true, "type": "object", "title": "Update Data", "description": "REQUIRED. Dictionary of field-value pairs to update on ALL matching documents. Can update any document field except vectors (metadata, source_blobs, etc.). All matched documents receive the SAME updates. Example: {'metadata.status': 'processed', 'metadata.reviewed': true}", "examples": [ { "metadata": { "reviewed": true, "status": "processed" } }, { "metadata.processing_complete": true } ] } }, "type": "object", "required": [ "update_data" ], "title": "BulkUpdateDocumentsRequest", "description": "Request model for bulk updating documents by filters.\n\nUpdates ALL documents matching the provided filters with the SAME update_data.\nFor updating specific documents by ID or different values per document, use BatchUpdateDocumentsRequest.\n\nUse Cases:\n - Update all pending documents to processed\n - Update all documents from a specific date range\n - Apply uniform changes across filtered document sets\n\nRequirements:\n - update_data: REQUIRED - fields to update on all matching documents\n - filters: OPTIONAL - if omitted, updates ALL documents in collection", "examples": [ { "description": "Update all pending documents to processed", "filters": { "AND": [ { "field": "metadata.status", "operator": "eq", "value": "pending" } ] }, "update_data": { "metadata": { "status": "processed" } } }, { "description": "Update all documents in collection (no filters)", "update_data": { "metadata": { "version": 2 } } } ] }, "BulkUpdateDocumentsResponse": { "properties": { "updated_count": { "type": "integer", "title": "Updated Count", "description": "Number of documents that were updated." }, "message": { "type": "string", "title": "Message", "default": "Documents updated successfully" } }, "type": "object", "required": [ "updated_count" ], "title": "BulkUpdateDocumentsResponse", "description": "Response model for bulk document update operation." }, "CacheConfig": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether caching is enabled for this retriever", "default": true }, "ttl_seconds": { "type": "integer", "minimum": 0.0, "title": "Ttl Seconds", "description": "Time-to-live for cached results in seconds. Default: 1 hour", "default": 3600 }, "cache_stage_names": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cache Stage Names", "description": "List of stage names to cache results after. Stage names must match the stage_name field in the retriever's stages. If not specified, caches the final results after all stages. Examples: ['semantic_search'], ['semantic_search', 'rerank']" }, "exclude_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Fields to exclude from caching (e.g., PII fields)" }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/CacheStatistics" }, { "type": "null" } ], "description": "Cache performance statistics" } }, "type": "object", "title": "CacheConfig", "description": "Configuration for retriever result caching.\n\nControls how retriever results are cached to improve performance\nand reduce redundant compute.\n\nCaching can be configured at specific stages in the retriever pipeline.\nIf no stages are specified, the final results are cached by default." }, "CachePerformanceResponse": { "properties": { "retriever_id": { "type": "string", "title": "Retriever Id", "description": "Retriever identifier" }, "time_range": { "$ref": "#/components/schemas/api__analytics__models__TimeRange", "description": "Time range" }, "cache_hit_rate": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Cache Hit Rate", "description": "Overall cache hit rate" }, "total_cache_hits": { "type": "integer", "title": "Total Cache Hits", "description": "Total cache hits" }, "total_cache_misses": { "type": "integer", "title": "Total Cache Misses", "description": "Total cache misses" }, "avg_cache_hit_latency_ms": { "type": "number", "title": "Avg Cache Hit Latency Ms", "description": "Average latency on cache hit" }, "avg_cache_miss_latency_ms": { "type": "number", "title": "Avg Cache Miss Latency Ms", "description": "Average latency on cache miss" }, "hourly_breakdown": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Hourly Breakdown", "description": "Hourly cache performance" } }, "type": "object", "required": [ "retriever_id", "time_range", "cache_hit_rate", "total_cache_hits", "total_cache_misses", "avg_cache_hit_latency_ms", "avg_cache_miss_latency_ms", "hourly_breakdown" ], "title": "CachePerformanceResponse", "description": "Cache performance metrics.", "examples": [ { "avg_cache_hit_latency_ms": 5.2, "avg_cache_miss_latency_ms": 145.8, "cache_hit_rate": 0.78, "hourly_breakdown": [ { "hit_rate": 0.78, "hits": 145, "hour": "2025-10-28T10:00:00Z", "misses": 42 } ], "retriever_id": "ret_abc123", "time_range": { "end": "2025-10-29T00:00:00Z", "start": "2025-10-28T00:00:00Z" }, "total_cache_hits": 3456, "total_cache_misses": 978 } ] }, "CacheStatistics": { "properties": { "hit_count": { "type": "integer", "title": "Hit Count", "description": "Number of cache hits", "default": 0 }, "miss_count": { "type": "integer", "title": "Miss Count", "description": "Number of cache misses", "default": 0 }, "hit_rate": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Hit Rate", "description": "Cache hit rate (0.0 - 1.0)", "default": 0.0 }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "Total size of cached data in bytes", "default": 0 }, "entry_count": { "type": "integer", "title": "Entry Count", "description": "Number of entries in cache", "default": 0 }, "last_invalidated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Invalidated At", "description": "When the cache was last invalidated" } }, "type": "object", "title": "CacheStatistics", "description": "Statistics about cache performance." }, "CancelMigrationRequest": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Cancellation reason" } }, "type": "object", "title": "CancelMigrationRequest", "description": "Request to cancel a migration." }, "CancelMigrationResponse": { "properties": { "migration_id": { "type": "string", "title": "Migration Id", "description": "Migration ID" }, "status": { "$ref": "#/components/schemas/MigrationStatus", "description": "Current status" }, "cancelled_at": { "type": "string", "format": "date-time", "title": "Cancelled At", "description": "Cancellation timestamp" }, "message": { "type": "string", "title": "Message", "description": "Human-readable message" } }, "type": "object", "required": [ "migration_id", "status", "cancelled_at", "message" ], "title": "CancelMigrationResponse", "description": "Response after cancelling a migration." }, "CancelSubscriptionRequest": { "properties": { "immediate": { "type": "boolean", "title": "Immediate", "description": "Cancel NOW (Stripe Subscription.cancel) instead of at period end. Default False preserves the period-end behavior.", "default": false }, "invoice_now": { "type": "boolean", "title": "Invoice Now", "description": "With immediate=true: generate a final proration invoice.", "default": false } }, "type": "object", "title": "CancelSubscriptionRequest", "description": "Options for subscription cancellation (BACKE-2859)." }, "CancelSubscriptionResponse": { "properties": { "subscription_id": { "type": "string", "title": "Subscription Id" }, "cancel_at_period_end": { "type": "boolean", "title": "Cancel At Period End", "default": true }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "message": { "type": "string", "title": "Message", "default": "Subscription will cancel at end of current billing period" } }, "type": "object", "required": [ "subscription_id" ], "title": "CancelSubscriptionResponse", "description": "Response after cancelling a subscription." }, "ChangeEventResponse": { "properties": { "seq": { "type": "integer", "title": "Seq", "description": "Monotonic position within this org's feed." }, "cursor": { "type": "string", "title": "Cursor", "description": "Opaque cursor pointing AT this event." }, "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Namespace scope, if any." }, "event_type": { "type": "string", "title": "Event Type", "description": "Same vocabulary as webhook subscriptions." }, "resource_type": { "type": "string", "title": "Resource Type", "description": "First segment of event_type." }, "operation": { "type": "string", "title": "Operation", "description": "insert | update | delete | other." }, "payload": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "Shape is PER-EVENT-TYPE, not a stable contract \u2014 it mirrors whatever the originating call site already passes to WebhookClient.emit() for this event_type, and that shape may change independently of this endpoint's own versioning." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "seq", "cursor", "event_type", "resource_type", "operation", "created_at" ], "title": "ChangeEventResponse" }, "ChunkStrategy": { "type": "string", "enum": [ "none", "sentences", "paragraphs", "words", "characters" ], "title": "ChunkStrategy", "description": "Strategy for splitting page content into chunks." }, "ClarificationOption": { "properties": { "label": { "type": "string", "title": "Label", "description": "Option label" }, "description": { "type": "string", "title": "Description", "description": "Option description" }, "action": { "type": "string", "title": "Action", "description": "Recommended action/tool" } }, "type": "object", "required": [ "label", "description", "action" ], "title": "ClarificationOption", "description": "A single option presented to the user for clarifying intent.\n\nAttributes:\n label: Short label for the option (e.g., \"Search existing data\")\n description: Detailed explanation of what this option means\n action: Recommended tool/action to use if user selects this option" }, "CloneCollectionRequest": { "properties": { "collection_name": { "type": "string", "minLength": 1, "title": "Collection Name", "description": "REQUIRED. Name for the cloned collection. Must be unique and different from the source collection.", "examples": [ "product_embeddings_v2", "video_frames_clip_v2" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "OPTIONAL. Description override. If omitted, copies from source collection.", "examples": [ "Cloned from product_embeddings with CLIP v2" ] }, "source": { "anyOf": [ { "$ref": "#/components/schemas/SourceConfig-Input" }, { "type": "null" } ], "description": "OPTIONAL. Override source configuration. If omitted, copies from source collection. Allows switching between buckets or collections." }, "feature_extractor": { "anyOf": [ { "$ref": "#/components/schemas/shared__collection__features__extractors__models__FeatureExtractorConfig-Input" }, { "type": "null" } ], "description": "OPTIONAL. Override feature extractor configuration. If omitted, copies from source collection. This is where you'd change models, parameters, or field_passthrough." }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "description": "OPTIONAL. Override enabled status. If omitted, copies from source collection." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "OPTIONAL. Override metadata. If omitted, copies from source collection." }, "taxonomy_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaxonomyApplicationConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Taxonomy Applications", "description": "OPTIONAL. Override taxonomy applications. If omitted, copies from source collection." } }, "type": "object", "required": [ "collection_name" ], "title": "CloneCollectionRequest", "description": "Request to clone a collection with optional modifications.\n\n**Purpose:**\nCloning creates a NEW collection (with new ID) based on an existing one,\nallowing you to make changes that aren't allowed via PATCH (source,\nfeature_extractor, field_passthrough). This is the recommended way to\niterate on collection designs.\n\n**Clone vs Template vs Version:**\n- **Clone**: Copy THIS collection and modify it (for iteration/fixes)\n- **Template**: Create collection from a reusable pattern (for new projects)\n- **Version**: (Not implemented) - Use clone instead\n\n**Use Cases:**\n- Change feature extractor configuration without breaking production\n- Modify field_passthrough to include/exclude fields\n- Switch to different source (bucket or collection)\n- Test modifications before replacing production collection\n- Create variants (e.g., different embedding models)\n\n**All fields are OPTIONAL:**\n- Omit a field to keep the original value\n- Provide a field to override the original value\n- collection_name is REQUIRED (clones must have unique names)", "examples": [ { "collection_name": "product_embeddings_backup", "example_desc": "Clone with just a new name (exact copy)" }, { "collection_name": "product_embeddings_clip_v2", "description": "Updated to use CLIP v2 model", "example_desc": "Clone with different feature extractor", "feature_extractor": { "feature_extractor_name": "image_extractor", "input_mappings": { "image": "product_image" }, "parameters": { "model": "clip-vit-large-patch14" }, "version": "v2" } }, { "collection_name": "product_embeddings_staging", "example_desc": "Clone to different source bucket", "source": { "bucket_id": "bkt_products_staging", "type": "bucket" } } ] }, "CloneCollectionResponse": { "properties": { "collection": { "$ref": "#/components/schemas/CollectionModel", "description": "Cloned collection configuration with new collection_id." }, "source_collection_id": { "type": "string", "title": "Source Collection Id", "description": "ID of the source collection that was cloned." } }, "type": "object", "required": [ "collection", "source_collection_id" ], "title": "CloneCollectionResponse", "description": "Response after cloning a collection." }, "CloneNamespaceRequest": { "properties": { "namespace_name": { "type": "string", "minLength": 1, "title": "Namespace Name", "description": "Name for the cloned namespace (must be unique)", "examples": [ "production_staging", "backup_2024_01" ] }, "include_resources": { "anyOf": [ { "$ref": "#/components/schemas/CloneNamespaceResourcesConfig" }, { "type": "null" } ], "description": "Which resources to include. Defaults to collections + retrievers." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Override description. If omitted, copies from source.", "examples": [ "Staging clone from production" ] }, "source_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Organization Id", "description": "Source org ID for cross-org cloning (admin only).", "examples": [ "org_abc123" ] } }, "type": "object", "required": [ "namespace_name" ], "title": "CloneNamespaceRequest", "description": "Request to clone a namespace with all its data.\n\nClone creates a full copy of a namespace including:\n- Namespace configuration (extractors, indexes)\n- Buckets (metadata, references same S3 files)\n- Collections (full copy of all vectors/embeddings)\n- Retrievers (pipeline configuration)\n\n**Use Cases:**\n- Create staging environment from production\n- Backup namespace with all data\n- Fork namespace for experimentation\n\n**For config-only copy (no data), use templates instead:**\n- POST /templates/namespaces/from-namespace/{id}\n- POST /templates/namespaces/{template_id}/instantiate", "examples": [ { "description": "Staging clone with all data", "namespace_name": "production_staging" }, { "description": "Experiment fork - collections only", "include_resources": { "collections": true, "retrievers": false, "taxonomies": false }, "namespace_name": "ml_experiment" } ] }, "CloneNamespaceResourcesConfig": { "properties": { "collections": { "type": "boolean", "title": "Collections", "description": "Include collections (with all embeddings/vectors)", "default": true }, "retrievers": { "type": "boolean", "title": "Retrievers", "description": "Include retrievers", "default": true }, "taxonomies": { "type": "boolean", "title": "Taxonomies", "description": "Include taxonomies", "default": false } }, "type": "object", "title": "CloneNamespaceResourcesConfig", "description": "Configuration for which resources to include in clone." }, "CloneNamespaceResponse": { "properties": { "namespace": { "$ref": "#/components/schemas/NamespaceModel", "description": "Cloned namespace with new namespace_id" }, "source_namespace_id": { "type": "string", "title": "Source Namespace Id", "description": "Source namespace that was cloned" }, "status": { "type": "string", "title": "Status", "description": "Clone status: 'cloning', 'ready', or 'failed'", "default": "cloning" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "Task ID for tracking clone progress" }, "cloned_resources": { "anyOf": [ { "$ref": "#/components/schemas/ClonedResourceSummary" }, { "type": "null" } ], "description": "Summary of cloned resources (present when ready)" }, "primary_retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Retriever Id", "description": "Pre-allocated retriever ID for the primary cloned retriever. Present immediately so callers can navigate to the retriever detail page while the background task hydrates the rest of the data. None if source namespace has no retrievers." } }, "type": "object", "required": [ "namespace", "source_namespace_id" ], "title": "CloneNamespaceResponse", "description": "Response after initiating namespace clone." }, "CloneRetrieverRequest": { "properties": { "retriever_name": { "type": "string", "minLength": 1, "title": "Retriever Name", "description": "REQUIRED. Name for the cloned retriever. Must be unique and different from the source retriever.", "examples": [ "product_search_v2", "semantic_search_strict" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "OPTIONAL. Description override. If omitted, copies from source retriever.", "examples": [ "Cloned from product_search with stricter filters" ] }, "collection_identifiers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Collection Identifiers", "description": "OPTIONAL. Override target collections. If omitted, copies from source retriever. This allows you to apply the same retriever logic to different collections. Also accepts 'collection_ids' as an alias.", "examples": [ [ "products_v2" ], [ "col_abc123", "col_def456" ] ] }, "stages": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StageConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Stages", "description": "OPTIONAL. Override stage configurations. If omitted, copies from source retriever. This is where you'd fix typos, add stages, or tweak parameters." }, "input_schema": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/RetrieverInputSchemaField-Input", "description": "Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.)" }, "type": "object" }, { "type": "null" } ], "title": "Input Schema", "description": "OPTIONAL. Override input schema. If omitted, copies from source retriever." }, "budget_limits": { "anyOf": [ { "$ref": "#/components/schemas/BudgetLimits" }, { "type": "null" } ], "description": "OPTIONAL. Override budget limits. If omitted, copies from source retriever." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "OPTIONAL. Override tags. If omitted, copies from source retriever.", "examples": [ [ "v2", "production" ], [ "experimental", "clone" ] ] }, "display_config": { "anyOf": [ { "$ref": "#/components/schemas/DisplayConfig-Input" }, { "type": "null" } ], "description": "OPTIONAL. Override display configuration. If omitted, copies from source retriever." } }, "type": "object", "required": [ "retriever_name" ], "title": "CloneRetrieverRequest", "description": "Request to clone a retriever with optional modifications.\n\n**Purpose:**\nCloning creates a NEW retriever (with new ID) based on an existing one,\nallowing you to make changes that aren't allowed via PATCH (stages,\ninput_schema, collections). This is the recommended way to iterate on\nretriever designs.\n\n**Clone vs Template vs Version:**\n- **Clone**: Copy THIS retriever and modify it (for iteration/fixes)\n- **Template**: Create retriever from a reusable pattern (for new projects)\n- **Version**: (Not implemented) - Use clone instead\n\n**Use Cases:**\n- Fix a typo in a stage name without losing execution history\n- Add/remove stages while keeping the original intact\n- Change collections while preserving the original retriever\n- Test modifications before replacing production retriever\n- Create variants (e.g., \"strict\" vs \"relaxed\" versions)\n\n**All fields are OPTIONAL:**\n- Omit a field to keep the original value\n- Provide a field to override the original value\n- retriever_name is REQUIRED (clones must have unique names)", "examples": [ { "example_desc": "Clone with just a new name (exact copy)", "retriever_name": "product_search_backup" }, { "description": "Stricter version with higher min_score", "example_desc": "Clone with stricter filters", "retriever_name": "product_search_strict", "tags": [ "strict", "production" ] }, { "collection_identifiers": [ "products_staging" ], "example_desc": "Clone to different collections", "retriever_name": "product_search_staging", "tags": [ "staging" ] } ] }, "CloneRetrieverResponse": { "properties": { "retriever": { "$ref": "#/components/schemas/RetrieverConfig", "description": "Cloned retriever configuration with new retriever_id." }, "source_retriever_id": { "type": "string", "title": "Source Retriever Id", "description": "ID of the source retriever that was cloned." } }, "type": "object", "required": [ "retriever", "source_retriever_id" ], "title": "CloneRetrieverResponse", "description": "Response after cloning a retriever." }, "CloneTaxonomyRequest": { "properties": { "taxonomy_name": { "type": "string", "minLength": 1, "title": "Taxonomy Name", "description": "REQUIRED. Name for the cloned taxonomy. Must be unique and different from the source taxonomy.", "examples": [ "product_tags_v2", "org_hierarchy_strict" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "OPTIONAL. Description override. If omitted, copies from source taxonomy.", "examples": [ "Cloned from product_tags with updated retriever" ] }, "config": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FlatTaxonomyConfig-Input" }, { "$ref": "#/components/schemas/HierarchicalTaxonomyConfig-Input" } ], "discriminator": { "propertyName": "taxonomy_type", "mapping": { "flat": "#/components/schemas/FlatTaxonomyConfig-Input", "hierarchical": "#/components/schemas/HierarchicalTaxonomyConfig-Input" } } }, { "type": "null" } ], "title": "Config", "description": "OPTIONAL. Override taxonomy configuration. If omitted, copies from source taxonomy. This allows you to change retriever_id, input_mappings, enrichment_fields, or collection hierarchy." } }, "type": "object", "required": [ "taxonomy_name" ], "title": "CloneTaxonomyRequest", "description": "Request to clone a taxonomy with optional modifications.\n\n**Purpose:**\nCloning creates a NEW taxonomy (with new ID) based on an existing one,\nallowing you to make changes that aren't allowed via PATCH (config,\nretriever_id, collections). This is the recommended way to iterate on\ntaxonomy designs.\n\n**Clone vs Template vs Version:**\n- **Clone**: Copy THIS taxonomy and modify it (for iteration/fixes)\n- **Template**: Create taxonomy from a reusable pattern (for new projects)\n- **Version**: (Not implemented) - Use clone instead\n\n**Use Cases:**\n- Fix configuration errors without losing join history\n- Change retriever or input mappings\n- Change target collections\n- Test modifications before replacing production taxonomy\n- Create variants for different datasets\n\n**All fields are OPTIONAL:**\n- Omit a field to keep the original value\n- Provide a field to override the original value\n- taxonomy_name is REQUIRED (clones must have unique names)", "examples": [ { "example_desc": "Clone with just a new name (exact copy)", "taxonomy_name": "product_tags_backup" }, { "config": { "collection_id": "col_products_v1", "input_mappings": [ { "input_key": "image_vector", "path": "features.clip_v2", "source_type": "vector" } ], "retriever_id": "ret_clip_v2", "taxonomy_type": "flat" }, "description": "Updated with new CLIP retriever", "example_desc": "Clone with different retriever", "taxonomy_name": "product_tags_v2" } ] }, "CloneTaxonomyResponse": { "properties": { "taxonomy": { "$ref": "#/components/schemas/TaxonomyModel-Output", "description": "Cloned taxonomy configuration with new taxonomy_id." }, "source_taxonomy_id": { "type": "string", "title": "Source Taxonomy Id", "description": "ID of the source taxonomy that was cloned." } }, "type": "object", "required": [ "taxonomy", "source_taxonomy_id" ], "title": "CloneTaxonomyResponse", "description": "Response after cloning a taxonomy." }, "ClonedResourceSummary": { "properties": { "collections": { "type": "integer", "title": "Collections", "description": "Collections cloned", "default": 0 }, "retrievers": { "type": "integer", "title": "Retrievers", "description": "Retrievers cloned", "default": 0 }, "taxonomies": { "type": "integer", "title": "Taxonomies", "description": "Taxonomies cloned", "default": 0 }, "buckets": { "type": "integer", "title": "Buckets", "description": "Buckets cloned", "default": 0 }, "objects": { "type": "integer", "title": "Objects", "description": "Objects cloned", "default": 0 }, "points": { "type": "integer", "title": "Points", "description": "Vector points cloned", "default": 0 } }, "type": "object", "title": "ClonedResourceSummary", "description": "Summary of cloned resources." }, "CloudCostCategorySummary": { "properties": { "category": { "type": "string", "title": "Category" }, "category_label": { "type": "string", "title": "Category Label" }, "cloud_cost_usd": { "type": "number", "title": "Cloud Cost Usd" }, "margin_usd": { "type": "number", "title": "Margin Usd" }, "total_usd": { "type": "number", "title": "Total Usd" }, "line_items": { "items": { "$ref": "#/components/schemas/CloudCostLineItem" }, "type": "array", "title": "Line Items" } }, "type": "object", "required": [ "category", "category_label", "cloud_cost_usd", "margin_usd", "total_usd", "line_items" ], "title": "CloudCostCategorySummary" }, "CloudCostLineItem": { "properties": { "service": { "type": "string", "title": "Service" }, "description": { "type": "string", "title": "Description" }, "category": { "type": "string", "title": "Category" }, "cloud_cost_usd": { "type": "number", "title": "Cloud Cost Usd" }, "margin_usd": { "type": "number", "title": "Margin Usd" }, "total_usd": { "type": "number", "title": "Total Usd" }, "usage_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Usage Amount" }, "usage_unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Unit" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" } }, "type": "object", "required": [ "service", "description", "category", "cloud_cost_usd", "margin_usd", "total_usd" ], "title": "CloudCostLineItem" }, "ClusterApplicationConfig": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id", "description": "ID of the cluster to execute (must exist and use this collection as input)" }, "auto_execute_on_batch": { "type": "boolean", "title": "Auto Execute On Batch", "description": "Automatically execute cluster when batch processing completes for this collection. If False, cluster must be executed manually via API.", "default": true }, "min_document_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Document Threshold", "description": "Minimum number of documents required before executing cluster. If document_count < threshold, clustering is skipped. Useful to avoid clustering on small datasets." }, "cooldown_seconds": { "type": "integer", "title": "Cooldown Seconds", "description": "Minimum time (in seconds) between automatic cluster executions. Prevents excessive re-clustering on frequent batch completions. Default: 3600 seconds (1 hour).", "default": 3600 }, "execution_phase": { "type": "integer", "maximum": 3.0, "minimum": 1.0, "title": "Execution Phase", "description": "Which phase this cluster runs in. Default: 2 (CLUSTER phase, after taxonomies). Valid values: 1=TAXONOMY, 2=CLUSTER, 3=ALERT. Lower phases run earlier.", "default": 2 }, "priority": { "type": "integer", "maximum": 1000.0, "minimum": 0.0, "title": "Priority", "description": "Priority within the execution phase (higher = runs first)", "default": 0 } }, "type": "object", "required": [ "cluster_id" ], "title": "ClusterApplicationConfig", "description": "Configuration for automatic cluster execution on collection.\n\nSimilar to TaxonomyApplicationConfig, this attaches a cluster to a collection\nand defines when/how it should be automatically executed.\n\nUsed in CollectionModel.cluster_applications field.\n\nSupports execution phase ordering for unified post-processing with\ntaxonomies, clusters, and alerts.", "examples": [ { "auto_execute_on_batch": true, "cluster_id": "clust_product_categories", "cooldown_seconds": 3600, "min_document_threshold": 100 }, { "auto_execute_on_batch": true, "cluster_id": "clust_user_segments", "cooldown_seconds": 7200, "execution_phase": 2, "min_document_threshold": 500, "priority": 10 } ] }, "ClusterExecutionCentroid": { "properties": { "cluster_id": { "type": "string", "minLength": 1, "title": "Cluster Id", "description": "REQUIRED. Unique identifier for this cluster within the execution. Vector clustering uses a 'cl_' prefix with a numeric index (e.g., 'cl_0', 'cl_0_sub_1', 'cl_cluster_noise'); attribute clustering uses value-derived IDs (e.g., 'cl_cluster_0' flat, 'cl_photonics_2024' hierarchical). Used to reference this specific cluster in queries and enrichments. Consistent across executions if algorithm deterministic.", "examples": [ "cl_0", "cl_1", "cl_0_sub_1", "cl_0_sub_1_sub_0", "cl_cluster_noise", "cl_-1", "cl_cluster_0", "cl_photonics_2024" ] }, "num_members": { "type": "integer", "minimum": 0.0, "title": "Num Members", "description": "REQUIRED. Number of documents/points assigned to this cluster. Indicates cluster size for sizing bubbles in visualizations. Minimum: 1 (K-Means forces assignment). Can be 0 for noise clusters in HDBSCAN (cluster_id = -1).", "examples": [ 150, 42, 1 ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "OPTIONAL. Human-readable label generated by LLM (e.g., GPT-4o-mini). Automatically generated when llm_labeling.enabled = true in cluster config. NOT REQUIRED when LLM labeling disabled. Describes the semantic meaning of documents in this cluster. Example: 'Product Reviews', 'Technical Documentation', 'Customer Support'.", "examples": [ "Product Reviews", "Technical Documentation", "Customer Support", null ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "OPTIONAL. Detailed description generated by LLM. Automatically generated when llm_labeling.include_summary = true. NOT REQUIRED when LLM labeling disabled or summary not requested. Provides context about what types of documents are in this cluster. Useful for tooltips, expanded views, or detailed explanations.", "examples": [ "This cluster contains documents related to product reviews and customer feedback.", "Technical documentation and API references are grouped here.", null ] }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Keywords", "description": "OPTIONAL. List of semantic keywords generated by LLM. Automatically generated when llm_labeling.include_keywords = true. NOT REQUIRED when LLM labeling disabled or keywords not requested. Useful for search, filtering, and quick cluster understanding. Typically 3-5 keywords per cluster.", "examples": [ [ "reviews", "products", "feedback" ], [ "technical", "documentation", "api" ], [ "support", "customer", "help" ], null ] }, "mean_cosine_similarity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Cosine Similarity", "description": "Mean cosine similarity of members to centroid (higher = tighter cluster)." }, "min_cosine_similarity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Cosine Similarity", "description": "Minimum cosine similarity of any member to centroid (cluster boundary)." }, "centroid_vector": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Centroid Vector", "description": "OPTIONAL. The cluster centroid's embedding vector. Only populated when a single-execution GET is called with ?include_vectors=true (vectors are large \u2014 e.g. 15 centroids x 1024 floats \u2248 120KB \u2014 so they're opt-in and never included in execution LIST responses). Enables vector-input searches that use the centroid as the query even when the centroid document is no longer resolvable in the vector store (e.g. artifact-served clusters after a store wipe). Omitted from the response entirely when not requested." }, "representative_ids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RepresentativeDocument" }, "type": "array" }, { "type": "null" } ], "title": "Representative Ids", "description": "OPTIONAL. Representative documents (document_id + collection_id) offered to the LLM labeler for this cluster, capped upstream to a small sample (~16). Persisted so a labeling failure is diagnosable from the run record alone: absent/empty vs. present-but-unfetchable distinguishes 'no reps were ever selected' from 'reps existed but the fetch/resolution stage failed them' (MC-1128 durability)." } }, "type": "object", "required": [ "cluster_id", "num_members" ], "title": "ClusterExecutionCentroid", "description": "Centroid information from a clustering execution.\n\nRepresents a single cluster center from a clustering run, including\nLLM-generated semantic labels for human understanding.\n\nUse Cases:\n - Display cluster information in dashboards\n - Show cluster labels and summaries in UI\n - Group documents by semantic meaning\n - Filter/search by cluster keywords\n\nNote:\n This model is for execution metadata only (no visualization coordinates).\n For scatter plot coordinates, use ArtifactCentroid from the artifacts endpoint.", "examples": [ { "cluster_id": "cl_0", "description": "Cluster with full LLM labeling", "keywords": [ "reviews", "products", "feedback", "ratings" ], "label": "Product Reviews", "num_members": 150, "summary": "This cluster contains documents related to product reviews and customer feedback." }, { "cluster_id": "cl_1", "description": "Cluster without LLM labeling", "num_members": 42 }, { "cluster_id": "cl_2", "description": "Small cluster with label", "keywords": [ "single", "unique", "isolation" ], "label": "Single Member Cluster", "num_members": 1, "summary": "This cluster contains only one member." } ] }, "ClusterExecutionListStats": { "properties": { "total_executions": { "type": "integer", "minimum": 0.0, "title": "Total Executions", "description": "OPTIONAL (always provided). Total number of executions in current result set. Equals length of results array. Use for: - Display total count in UI ('Showing 10 of 100 executions'). - Validate pagination (total should match page_size \u00d7 pages). - Check if filters returned any results (0 = no matches). Note: This is the count in the current page, not all executions.", "default": 0, "examples": [ 10, 25, 100, 0 ] }, "executions_by_status": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Executions By Status", "description": "OPTIONAL (always provided). Count of executions grouped by status. Keys: 'pending', 'processing', 'completed', 'failed'. Values: Number of executions in each status. Use for: - Status distribution chart (pie/bar chart). - Health monitoring (high failed count = problem). - Progress tracking (pending + processing = in-flight jobs). Example: {'completed': 45, 'failed': 3, 'processing': 2, 'pending': 0}. Empty dict {} if no executions in result set.", "examples": [ { "completed": 45, "failed": 3, "processing": 2 }, { "completed": 100 }, {} ] }, "avg_execution_time_ms": { "type": "number", "minimum": 0.0, "title": "Avg Execution Time Ms", "description": "OPTIONAL (always provided). Average execution duration in milliseconds. Calculated as: mean(completed_at - created_at) for completed/failed executions. Excludes pending/processing executions (no completed_at yet). Use for: - Performance monitoring ('Average: 5.2 seconds'). - Trend analysis (is clustering getting slower over time?). - Capacity planning (estimate time for future runs). 0.0 if: No completed/failed executions in result set. Typical values: - Small datasets (< 100 docs): 1000-5000ms (1-5 seconds). - Medium datasets (100-1000 docs): 5000-30000ms (5-30 seconds). - Large datasets (1000+ docs): 30000-300000ms (30 seconds - 5 minutes).", "default": 0.0, "examples": [ 5234.5, 12890.3, 45678.9, 0.0 ] }, "total_documents_clustered": { "type": "integer", "minimum": 0.0, "title": "Total Documents Clustered", "description": "OPTIONAL (always provided). Total documents processed across all executions. Calculated as: sum(num_points) for all executions in result set. Use for: - Volume tracking ('Processed 10,000 documents'). - Cost estimation (larger datasets = more compute). - Data growth monitoring (compare over time). 0 if: No executions in result set. Note: Same document may be counted multiple times if re-clustered.", "default": 0, "examples": [ 10000, 50000, 150000, 0 ] }, "avg_num_clusters": { "type": "number", "minimum": 0.0, "title": "Avg Num Clusters", "description": "OPTIONAL (always provided). Average number of clusters found per execution. Calculated as: mean(num_clusters) for all executions in result set. Use for: - Clustering consistency check (stable avg = consistent results). - Algorithm tuning (avg too high/low may need parameter adjustment). - Trend analysis (is clustering finding more/fewer clusters over time?). 0.0 if: No executions in result set. Typical values: - Under-clustering: < 3 clusters (data may be too diverse). - Good clustering: 3-20 clusters (manageable, meaningful groups). - Over-clustering: > 20 clusters (too granular, hard to interpret).", "default": 0.0, "examples": [ 5.3, 12.7, 3.0, 0.0 ] } }, "type": "object", "title": "ClusterExecutionListStats", "description": "Aggregate statistics calculated across all executions in the current result set.\n\nProvides summary metrics for the filtered/searched execution history, useful for\ndashboards, monitoring, and trend analysis. Statistics are calculated only for\nthe executions returned in the current query (respects filters and pagination).\n\nUse Cases:\n - Display execution summary cards (\"5 completed, 2 failed, 3 pending\")\n - Show average execution time trend\n - Monitor clustering performance over time\n - Build execution health dashboard\n - Compare stats across different time periods (via filters)\n\nImportant:\n Stats reflect only the current result set, not all historical executions.\n Apply filters to calculate stats for specific time ranges or statuses.", "examples": [ { "avg_execution_time_ms": 8234.5, "avg_num_clusters": 5.2, "description": "Healthy execution stats (mostly successful)", "executions_by_status": { "completed": 45, "failed": 3, "pending": 0, "processing": 2 }, "total_documents_clustered": 50000, "total_executions": 50 }, { "avg_execution_time_ms": 12890.3, "avg_num_clusters": 7.5, "description": "All completed executions", "executions_by_status": { "completed": 10 }, "total_documents_clustered": 15000, "total_executions": 10 }, { "avg_execution_time_ms": 0.0, "avg_num_clusters": 0.0, "description": "Empty result set (no executions)", "executions_by_status": {}, "total_documents_clustered": 0, "total_executions": 0 } ] }, "ClusterExecutionMetric": { "properties": { "execution_id": { "type": "string", "title": "Execution Id", "description": "Execution identifier" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At", "description": "Execution start time" }, "duration_seconds": { "type": "number", "title": "Duration Seconds", "description": "Execution duration" }, "num_documents": { "type": "integer", "title": "Num Documents", "description": "Number of documents clustered" }, "num_clusters": { "type": "integer", "title": "Num Clusters", "description": "Number of clusters created" }, "status": { "type": "string", "title": "Status", "description": "Execution status" }, "algorithm": { "type": "string", "title": "Algorithm", "description": "Clustering algorithm used" } }, "type": "object", "required": [ "execution_id", "started_at", "duration_seconds", "num_documents", "num_clusters", "status", "algorithm" ], "title": "ClusterExecutionMetric", "description": "Single cluster execution metrics." }, "ClusterExecutionMetrics": { "properties": { "silhouette_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": -1.0 }, { "type": "null" } ], "title": "Silhouette Score", "description": "OPTIONAL. Silhouette score measuring cluster cohesion and separation. Range: -1 to +1. Interpretation: +1.0 = Perfect clustering (documents far from other clusters, close to own cluster). 0.0 = Overlapping clusters (documents on cluster boundaries). -1.0 = Poor clustering (documents assigned to wrong clusters). Practical thresholds: 0.7 to 1.0 = Excellent clustering. 0.5 to 0.7 = Good clustering. 0.25 to 0.5 = Weak clustering, consider different parameters. Below 0.25 = Poor clustering, reconfigure or more data needed. null = metric not calculated (too few points or clustering failed).", "examples": [ 0.85, 0.67, 0.42, null ] }, "davies_bouldin_index": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Davies Bouldin Index", "description": "OPTIONAL. Davies-Bouldin index measuring cluster separation. Range: 0 to +\u221e (lower is better, no upper bound). Interpretation: 0.0 = Perfect separation (impossible in practice). 0.0 to 1.0 = Excellent separation. 1.0 to 2.0 = Good separation. Above 2.0 = Poor separation, clusters overlap. Formula: Average ratio of intra-cluster to inter-cluster distances. Use when: Validating that clusters are distinct and well-separated. null = metric not calculated (too few points or clustering failed).", "examples": [ 0.45, 1.23, 2.67, null ] }, "calinski_harabasz_score": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "null" } ], "title": "Calinski Harabasz Score", "description": "OPTIONAL. Calinski-Harabasz score (also called Variance Ratio Criterion). Range: 0 to +\u221e (higher is better, no strict upper bound). Interpretation: Higher values indicate denser, more compact clusters. No universal threshold - compare relative values across runs. Typical good values: 100-1000+ (dataset dependent). Formula: Ratio of between-cluster to within-cluster dispersion. Use when: Comparing different numbers of clusters for the same dataset. Note: Biased toward algorithms that produce spherical, equally-sized clusters. null = metric not calculated (too few points or clustering failed).", "examples": [ 456.78, 1234.56, 89.12, null ] } }, "type": "object", "title": "ClusterExecutionMetrics", "description": "Quality metrics for evaluating clustering execution performance.\n\nProvides statistical measures to assess the quality of the clustering results.\nHigher quality clusters have better cohesion (documents within clusters are similar)\nand separation (clusters are distinct from each other).\n\nUse Cases:\n - Compare quality across multiple clustering executions\n - Determine optimal number of clusters for a dataset\n - Validate clustering algorithm performance\n - Track clustering quality over time\n - Debug clustering issues (poor metrics indicate problems)\n\nInterpretation:\n - Use silhouette_score as primary quality indicator (0.5+ = good, 0.7+ = excellent)\n - Lower davies_bouldin_index indicates better-separated clusters\n - Higher calinski_harabasz_score indicates denser, better-separated clusters\n\nNote:\n All metrics are OPTIONAL and only present if clustering completed successfully.\n Failed executions return null for all metrics.", "examples": [ { "calinski_harabasz_score": 1234.56, "davies_bouldin_index": 0.42, "description": "Excellent clustering quality", "silhouette_score": 0.85 }, { "calinski_harabasz_score": 678.34, "davies_bouldin_index": 0.89, "description": "Good clustering quality", "silhouette_score": 0.67 }, { "calinski_harabasz_score": 45.12, "davies_bouldin_index": 2.45, "description": "Poor clustering quality (needs tuning)", "silhouette_score": 0.23 }, { "description": "Metrics not available (failed execution)" } ] }, "ClusterExecutionResult": { "properties": { "run_id": { "type": "string", "pattern": "^run_[a-zA-Z0-9]+$", "title": "Run Id", "description": "REQUIRED. Unique identifier for this specific clustering execution. Format: 'run_' prefix followed by random alphanumeric string. Used to retrieve specific execution artifacts and results. Each re-execution of the same cluster creates a new run_id. References execution artifacts in S3 and MongoDB.", "examples": [ "run_a8e270953254754b", "run_b3f58210ab", "run_xyz789" ] }, "cluster_id": { "type": "string", "pattern": "^clust_[a-zA-Z0-9]+$", "title": "Cluster Id", "description": "REQUIRED. Parent cluster configuration that was executed. Format: 'clust_' prefix followed by random alphanumeric string. Links this execution back to the cluster definition. Multiple executions can share the same cluster_id.", "examples": [ "clust_ae3e28a429", "clust_xyz789", "clust_abc123" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "title": "Status", "description": "REQUIRED. Current status of the clustering execution. Values: 'pending' = Job queued, waiting to start. 'processing' = Clustering algorithm running (may take minutes for large datasets). 'completed' = Clustering finished successfully, results available. 'failed' = Clustering failed, check error_message for details. Status changes: pending \u2192 processing \u2192 (completed OR failed). Poll this field to track job progress.", "examples": [ "completed", "processing", "pending", "failed" ] }, "num_clusters": { "type": "integer", "minimum": 0.0, "title": "Num Clusters", "description": "REQUIRED. Number of clusters found by the clustering algorithm. Range: 1 to num_points (though typically much lower). Interpretation: Too few clusters = overgeneralization, may need lower n_clusters param. Too many clusters = overfitting, may need higher n_clusters param. Optimal value depends on dataset and use case. Available immediately upon completion, even if metrics fail.", "examples": [ 3, 5, 10, 25 ] }, "num_points": { "type": "integer", "minimum": 0.0, "title": "Num Points", "description": "REQUIRED. Total number of documents/points that were clustered. Equals the count of documents in the collection at execution time. Note: This may differ across executions if documents were added/removed. Used to calculate metrics and validate clustering quality. Minimum 2 points required for clustering (1 cluster per point otherwise).", "examples": [ 100, 1000, 50000 ] }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/ClusterExecutionMetrics" }, { "type": "null" } ], "description": "OPTIONAL. Quality metrics evaluating clustering performance. NOT REQUIRED - only present for successful executions. null if: - Execution is still pending/processing. - Execution failed. - Too few points to calculate metrics (need 2+ points). Contains silhouette_score, davies_bouldin_index, calinski_harabasz_score. Use to compare quality across multiple executions." }, "centroids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ClusterExecutionCentroid" }, "type": "array" }, { "type": "null" } ], "title": "Centroids", "description": "OPTIONAL. List of cluster centroids with semantic labels. NOT REQUIRED - only present for completed executions with LLM labeling enabled. Length: equals num_clusters. Each centroid contains: - cluster_id: Identifier for the cluster (e.g., 'cl_0'). - num_members: Count of documents in this cluster. - label: Human-readable cluster name (e.g., 'Product Reviews'). - summary: Brief description of cluster content. - keywords: Array of representative terms. null if: - Execution pending/processing/failed. - LLM labeling not configured. Use for: Displaying cluster summaries in UI, filtering by cluster." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "REQUIRED. Timestamp when the clustering execution started. ISO 8601 format with timezone (UTC). Used to: - Sort executions chronologically. - Calculate execution duration (completed_at - created_at). - Filter execution history by date range. Always present, even for failed executions.", "examples": [ "2025-11-13T13:20:40.122000Z", "2025-11-13T10:00:00.000000Z" ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "OPTIONAL. Timestamp when the clustering execution finished. ISO 8601 format with timezone (UTC). NOT REQUIRED - only present for completed or failed executions. null if: status is 'pending' or 'processing'. Use to: - Calculate execution duration (completed_at - created_at). - Show when results became available. Present for both successful and failed executions.", "examples": [ "2025-11-13T13:25:40.122000Z", "2025-11-13T10:05:32.456000Z", null ] }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "OPTIONAL. Error message if the clustering execution failed. NOT REQUIRED - only present when status is 'failed'. null if: execution succeeded or is still in progress. Contains: - Human-readable error description. - Possible causes and suggested fixes. - Stack trace details (for debugging). Common errors: - 'Insufficient documents for clustering' (need 2+ docs). - 'Feature extractor not found' (invalid collection config). - 'Out of memory' (dataset too large for algorithm). Use for: Debugging failed executions and user error messages.", "examples": [ "Insufficient documents for clustering: need at least 2 documents", "Feature extractor 'invalid_extractor' not found in collection", "Clustering algorithm failed: NaN values in embeddings", null ] }, "error_traceback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Traceback", "description": "OPTIONAL. Tail-truncated Python traceback captured where the execution failed (engine Ray driver or API-side submission). NOT REQUIRED - only present when status is 'failed' and a traceback was captured. null if: execution succeeded, is still in progress, or the failure predates traceback capture. Use for: debugging failed executions when error_message alone (e.g. a raw Ray internals string) is not actionable." }, "llm_labeling_errors": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Llm Labeling Errors", "description": "OPTIONAL. List of errors encountered during LLM labeling. NOT REQUIRED - only present when LLM labeling was attempted and encountered errors. null if: - LLM labeling was not enabled. - LLM labeling succeeded for all clusters. - Execution is still in progress. Each error is a JSON string containing: - 'error': Human-readable error message. - 'clusters': List of cluster IDs affected by this error. Common errors: - 'LLM API timeout for 2 clusters' (network/API issues). - 'OpenAI rate limit exceeded' (quota exhausted). - 'Invalid model name: gpt-3.5' (config error). - 'No representative documents for cluster cl_3' (empty cluster). Use for: - Debugging why some clusters have fallback labels. - Identifying LLM API issues without failing entire clustering. - Warning users about partial labeling success.", "examples": [ [ "{\"error\": \"LLM API timeout\", \"clusters\": [\"cl_3\", \"cl_5\"]}", "{\"error\": \"No representative documents\", \"clusters\": [\"cl_1\"]}" ], [ "{\"error\": \"OpenAI rate limit exceeded\", \"clusters\": [\"cl_0\"]}" ], null ] }, "source_documents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Source Documents", "description": "OPTIONAL. Authoritative count of documents in the source collection(s) at cluster time \u2014 an INDEPENDENT Mongo count, not derived from the index/parquet path the clustering consumed. 'What SHOULD have clustered.' Compare with vectors_retrieved: a positive index_gap means the index could not serve some documents' vectors, so the result is computed on a biased sample." }, "vectors_retrieved": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Vectors Retrieved", "description": "OPTIONAL. Number of vectors the index actually SERVED into the clustering (parquet rows). Below source_documents \u21d2 index gap (MI-4159 signature)." }, "vectors_clustered": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Vectors Clustered", "description": "OPTIONAL. Number of documents that left the algorithm with a cluster assignment. Below vectors_retrieved for an assign-every-point algorithm \u21d2 a silent pipeline drop; for a noise-producing algorithm the gap is expected noise." }, "index_gap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Index Gap", "description": "source_documents \u2212 vectors_retrieved (>0 = index gap)." }, "pipeline_drop": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pipeline Drop", "description": "vectors_retrieved \u2212 vectors_clustered." }, "input_reconciliation_ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Input Reconciliation Ok", "description": "OPTIONAL. False when an UNEXPECTED input-count gap was detected (index gap, or a pipeline drop under an assign-every-point algorithm). Expected noise does not set this False." }, "input_reconciliation_reasons": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Input Reconciliation Reasons", "description": "Human-readable descriptions of any reconciliation gaps." }, "pipeline_drop_expected_as_noise": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pipeline Drop Expected As Noise", "description": "OPTIONAL. True when the algorithm legitimately leaves points unassigned (HDBSCAN/DBSCAN/OPTICS/EVoC), so a positive pipeline_drop is expected noise rather than a silent drop." }, "label_overrides": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Label Overrides", "description": "OPTIONAL. User-applied cluster label renames for this run, keyed by cluster_id (e.g. {'cl_0': 'Gadget Reviews'}). Written via PATCH /v1/clusters/{cluster_id}/executions/{run_id}/labels and persisted on the execution record (per-run, since cluster_ids are per-run) \u2014 no re-execution required. When present, centroids[].label and the visualization endpoint's cluster_label fields are already remapped server-side; this map is returned so clients can distinguish user renames from LLM/auto labels. Omitted from the response entirely when no overrides exist (schema-additive).", "examples": [ { "cl_0": "Gadget Reviews" }, null ] }, "run_name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Run Name", "description": "OPTIONAL. Human-friendly name for this execution run (e.g. 'July tuning baseline'), set via PATCH /v1/clusters/{cluster_id}/executions/{run_id}/name and persisted on the execution record \u2014 no re-execution required. Editable at any time; capped at 120 characters. Use it to tell runs apart in the run selector / execution history instead of raw run_ids. Omitted from the response entirely when the run was never named (schema-additive, same rule as label_overrides).", "examples": [ "July tuning baseline", null ] }, "layout_stability_applied": { "anyOf": [ { "type": "string", "enum": [ "transform", "aligned", "none" ] }, { "type": "null" } ], "title": "Layout Stability Applied", "description": "OPTIONAL. What layout stabilization actually happened on this execution (LS-5). 'transform' = coordinates were projected through the previous run's saved reducer (existing documents pixel-stable). 'aligned' = the fresh layout was registered onto the previous run's coordinates via a least-squares similarity transform over shared documents. 'none' = raw independent layout (stability disabled, first run, or a documented skip \u2014 see layout_stability_reason). Omitted for executions that predate LS-5 (schema-additive).", "examples": [ "aligned", "transform", "none", null ] }, "layout_stability_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Layout Stability Reason", "description": "OPTIONAL. Human-readable explanation of layout_stability_applied \u2014 e.g. 'aligned to previous run on 412 shared documents' or 'only 3 shared documents with previous run (minimum 20)'. Omitted when absent (schema-additive).", "examples": [ "aligned to previous run on 412 shared documents", null ] } }, "type": "object", "required": [ "run_id", "cluster_id", "status", "num_clusters", "num_points", "created_at" ], "title": "ClusterExecutionResult", "description": "Complete results from a single clustering execution.\n\nRepresents the outcome of running a clustering algorithm on a collection's documents.\nEach execution creates a snapshot of clustering results at a point in time, including\nthe clusters found, quality metrics, and semantic labels.\n\nUse Cases:\n - Display clustering execution history in UI\n - Compare clustering quality across multiple runs\n - Track execution status for long-running jobs\n - Debug failed clustering attempts\n - View cluster summaries and labels for analysis\n\nWorkflow:\n 1. Create cluster configuration \u2192 POST /clusters\n 2. Execute clustering \u2192 POST /clusters/{id}/execute\n 3. Poll execution status \u2192 GET /clusters/{id}/executions\n 4. View execution history \u2192 POST /clusters/{id}/executions/list\n\nStatus Lifecycle:\n pending \u2192 processing \u2192 completed (or failed)\n\nNote:\n Execution results are immutable once completed. Re-running clustering\n creates a new execution result with a new run_id.", "examples": [ { "centroids": [ { "cluster_id": "cl_0", "keywords": [ "product", "review", "quality" ], "label": "Product Reviews", "num_members": 45, "summary": "Customer feedback about products" }, { "cluster_id": "cl_1", "keywords": [ "help", "issue", "support" ], "label": "Support Tickets", "num_members": 35, "summary": "Technical support requests" }, { "cluster_id": "cl_2", "keywords": [ "feature", "request", "suggestion" ], "label": "Feature Requests", "num_members": 20, "summary": "User feature suggestions" } ], "cluster_id": "clust_ae3e28a429", "completed_at": "2025-11-13T13:25:40.122000Z", "created_at": "2025-11-13T13:20:40.122000Z", "description": "Completed execution with excellent metrics", "metrics": { "calinski_harabasz_score": 1234.56, "davies_bouldin_index": 0.42, "silhouette_score": 0.85 }, "num_clusters": 3, "num_points": 100, "run_id": "run_a8e270953254754b", "status": "completed" }, { "cluster_id": "clust_xyz789", "created_at": "2025-11-13T14:00:00.000000Z", "description": "Execution in progress", "num_clusters": 0, "num_points": 500, "run_id": "run_b3f58210ab", "status": "processing" }, { "cluster_id": "clust_abc123", "completed_at": "2025-11-13T12:00:05.123000Z", "created_at": "2025-11-13T12:00:00.000000Z", "description": "Failed execution with error details", "error_message": "Insufficient documents for clustering: need at least 2 documents, found 1", "num_clusters": 0, "num_points": 1, "run_id": "run_xyz789", "status": "failed" } ] }, "ClusterGroup": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id", "description": "Group identifier (e.g., 'cl_0')" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Human-readable label" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Group summary" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Keywords", "description": "Semantic keywords" }, "member_count": { "type": "integer", "title": "Member Count", "description": "Number of documents in this group" } }, "type": "object", "required": [ "cluster_id", "member_count" ], "title": "ClusterGroup", "description": "A single cluster group." }, "ClusterGroupsResponse": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "total_groups": { "type": "integer", "title": "Total Groups" }, "total_documents": { "type": "integer", "title": "Total Documents" }, "groups": { "items": { "$ref": "#/components/schemas/ClusterGroup" }, "type": "array", "title": "Groups" } }, "type": "object", "required": [ "cluster_id", "total_groups", "total_documents", "groups" ], "title": "ClusterGroupsResponse", "description": "Response containing all groups for a cluster." }, "ClusterListStats": { "properties": { "total_clusters": { "type": "integer", "title": "Total Clusters", "description": "Total number of clusters in the result", "default": 0 }, "total_documents": { "type": "integer", "title": "Total Documents", "description": "Total number of documents across all clusters", "default": 0 }, "avg_documents_per_cluster": { "type": "number", "title": "Avg Documents Per Cluster", "description": "Average number of documents per cluster", "default": 0.0 }, "clusters_by_status": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Clusters By Status", "description": "Count of clusters grouped by status" } }, "type": "object", "title": "ClusterListStats", "description": "Aggregate statistics for a list of clusters." }, "ClusterMetadata": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id", "description": "Unique cluster job identifier" }, "cluster_name": { "type": "string", "title": "Cluster Name", "description": "Human-readable cluster name" }, "namespace_id": { "type": "string", "title": "Namespace Id", "description": "Namespace this cluster belongs to" }, "input_collections": { "items": { "type": "string" }, "type": "array", "title": "Input Collections", "description": "Source collection IDs that were clustered" }, "source_bucket_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source Bucket Ids", "description": "Source bucket IDs that the input collections originated from. Enables bucket lineage tracking." }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters", "description": "Optional filters that were applied to pre-filter documents before clustering" }, "cluster_type": { "type": "string", "enum": [ "vector", "attribute" ], "title": "Cluster Type", "description": "Type of clustering: vector (embedding-based) or attribute (metadata-based)" }, "feature_uris": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Feature Uris", "description": "Feature URIs that were clustered (mixpeek://{extractor}@{version}/{output}). Only for vector clustering." }, "multi_feature_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Multi Feature Strategy", "description": "Strategy used if multiple features (concatenate/independent/weighted). Only for vector clustering." }, "learned_weights": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Learned Weights", "description": "Automatically learned feature weights (when multi_feature_strategy='weighted'). Keys are feature URIs, values are learned weights. Only populated after clustering execution completes." }, "learning_quality_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Learning Quality Score", "description": "Clustering quality score from weight learning (e.g., silhouette score). Only populated when multi_feature_strategy='weighted' and weights were learned." }, "effective_feature_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effective Feature Method", "description": "Method for calculating cluster centroids (mean/median/medoid). Only for vector clustering." }, "face_cluster_merge": { "anyOf": [ { "$ref": "#/components/schemas/FaceClusterMergeConfig" }, { "type": "null" } ], "description": "Stored post-HDBSCAN face-identity merge config. Populated from `vector_config.face_cluster_merge` at cluster creation and replayed into `ClusteringConfig` on every execute. Only applies to vector clustering." }, "sample_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Size", "description": "Stored per-execution document cap. Populated from `vector_config.sample_size` at cluster creation and replayed into `ClusteringConfig` on every `POST /v1/clusters/{id}/execute` so re-runs stay consistent with the original config. When None, the export is uncapped (bounded by the engine's 100,000 safety limit). Only applies to vector clustering." }, "preprocessing_steps": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Preprocessing Steps", "description": "Stored preprocessing steps from vector_config. Replayed into ClusteringConfig on every execute." }, "hierarchical_vector": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Hierarchical Vector", "description": "Whether recursive sub-clustering is enabled for vector clustering." }, "max_hierarchy_depth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Hierarchy Depth", "description": "Maximum recursion depth for hierarchical sub-clustering." }, "vis_n_components": { "anyOf": [ { "type": "integer", "enum": [ 2, 3 ] }, { "type": "null" } ], "title": "Vis N Components", "description": "Stored visualization dimensionality (2D or 3D). Replayed into ClusteringConfig on every execute as the default." }, "layout_stability": { "anyOf": [ { "type": "string", "enum": [ "none", "transform", "align" ] }, { "type": "null" } ], "title": "Layout Stability", "description": "Stored layout-stability mode (LS-5) from vector_config.layout_stability. Replayed into ClusteringConfig on every execute. When unset, executions default to 'align' (keep the map stable across runs via post-hoc registration)." }, "clustered_attributes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Clustered Attributes", "description": "Attribute field names that were clustered. Only for attribute clustering." }, "hierarchical_grouping": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Hierarchical Grouping", "description": "Whether hierarchical clustering was used. Only for attribute clustering." }, "aggregation_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Aggregation Method", "description": "Method for aggregating attributes (most_frequent/first/last). Only for attribute clustering." }, "output_collection_ids": { "items": { "type": "string" }, "type": "array", "title": "Output Collection Ids", "description": "Collection IDs where cluster documents are stored. For single output: list with one collection ID. For per-feature output: list with one collection ID per feature." }, "output_collection_names": { "items": { "type": "string" }, "type": "array", "title": "Output Collection Names", "description": "Names of output collections. Corresponds to output_collection_ids." }, "algorithm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Algorithm", "description": "Clustering algorithm used (hdbscan, kmeans, attribute_based, etc.)" }, "algorithm_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Algorithm Params", "description": "Algorithm-specific parameters (not used for attribute_based)" }, "enrich_source": { "type": "boolean", "title": "Enrich Source", "description": "Whether source documents were enriched with cluster_id", "default": false }, "source_enrichment_config": { "anyOf": [ { "$ref": "#/components/schemas/SourceEnrichmentConfig" }, { "type": "null" } ], "description": "Configuration for source enrichment (if enrich_source=True)" }, "llm_labeling": { "anyOf": [ { "$ref": "#/components/schemas/LLMLabeling-Output" }, { "type": "null" } ], "description": "Configuration for LLM-based cluster labeling (applies to all cluster types)" }, "num_clusters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Clusters", "description": "Number of clusters found (excludes noise/outliers, populated after execution)" }, "num_documents_clustered": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Documents Clustered", "description": "Total documents processed" }, "execution_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Execution Time Seconds", "description": "Time taken to complete clustering" }, "quality_metrics": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Quality Metrics", "description": "Clustering quality metrics (silhouette_score, davies_bouldin_score, calinski_harabasz_score, etc.). Open diagnostic bag like ClusteringResult.metrics: mostly numeric, but the three-state degenerate flag (False | reason string) and its prose degenerate_detail are non-numeric, so the value type is Any. A float-only type 400'd every GET on a cluster whose run flagged a degenerate result (MC-1256's read-path sibling: the write side persisted the string, this read side then rejected it)." }, "hierarchy_detected": { "type": "boolean", "title": "Hierarchy Detected", "description": "Whether implicit hierarchy was detected (multi-feature independent) or created (hierarchical attributes)", "default": false }, "parent_cluster_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Cluster Id", "description": "For child clusters in hierarchy" }, "child_cluster_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Child Cluster Ids", "description": "For parent clusters" }, "hierarchy_relationships": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Hierarchy Relationships", "description": "Parent-child relationships detected from cluster membership overlap" }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "Cluster job status (propagated from TaskService)", "default": "PENDING" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if cluster execution failed. Propagated from TaskService." }, "failure_category": { "anyOf": [ { "$ref": "#/components/schemas/FailureCategory" }, { "type": "null" } ], "description": "Machine-readable failure classification. Same enum as batch failure_category." }, "last_execution_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Execution Task Id", "description": "Most recent task ID for this cluster" }, "last_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Run Id", "description": "Most recent execution run ID" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When cluster was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When cluster was last updated" }, "last_executed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Executed At", "description": "Last execution timestamp" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When clustering completed successfully" }, "llm_labeling_errors": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Llm Labeling Errors", "description": "List of errors encountered during LLM labeling (if any). Stored in MongoDB cluster metadata only, NOT in Qdrant cluster documents. Used to track LLM failures while allowing fallback labels to work." }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional user-defined metadata" } }, "type": "object", "required": [ "cluster_name", "namespace_id", "input_collections", "cluster_type" ], "title": "ClusterMetadata", "description": "Cluster job metadata stored in MongoDB clusters collection.\n\nThis is separate from cluster documents themselves. Tracks job-level\nconfiguration, status, and summary statistics.\n\nSupports both vector and attribute clustering with appropriate metadata." }, "ClusterModel": { "properties": { "collection_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Collection Ids", "description": "Collections to cluster together" }, "cluster_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cluster Name", "description": "Optional human-friendly name for the clustering job" }, "cluster_type": { "$ref": "#/components/schemas/ClusterType", "description": "Vector or attribute clustering", "default": "vector" }, "vector_config": { "anyOf": [ { "$ref": "#/components/schemas/VectorBasedConfig-Output" }, { "type": "null" } ], "description": "Required when cluster_type is 'vector'" }, "attribute_config": { "anyOf": [ { "$ref": "#/components/schemas/AttributeBasedConfig" }, { "type": "null" } ], "description": "Required when cluster_type is 'attribute'" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Output" }, { "type": "null" } ], "description": "Optional filters to pre-filter documents before clustering (same format as list documents). Applied during Qdrant scroll before parquet export. Useful for clustering subsets like: status='active', category='electronics', etc." }, "llm_labeling": { "anyOf": [ { "$ref": "#/components/schemas/LLMLabeling-Output" }, { "type": "null" } ], "description": "Optional configuration for LLM-based cluster labeling. When provided with enabled=True, clusters will have semantic labels generated by LLM instead of generic labels like 'Cluster 0'. When not provided or enabled=False, uses fallback labels." }, "enrich_source_collection": { "type": "boolean", "title": "Enrich Source Collection", "description": "If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern.", "default": false }, "source_enrichment_config": { "anyOf": [ { "$ref": "#/components/schemas/SourceEnrichmentConfig" }, { "type": "null" } ], "description": "Configuration for source collection enrichment (only used if enrich_source_collection=True). Controls which fields are added to source documents and field naming conventions." }, "auto_execute_on_batch": { "type": "boolean", "title": "Auto Execute On Batch", "description": "Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API.", "default": false }, "auto_execute_min_documents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Auto Execute Min Documents", "description": "Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped." }, "auto_execute_cooldown_seconds": { "type": "integer", "title": "Auto Execute Cooldown Seconds", "description": "Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).", "default": 3600 }, "cluster_id": { "type": "string", "title": "Cluster Id", "description": "Unique cluster identifier" }, "parquet_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parquet Path", "description": "S3 path to parquet files with cluster data" }, "members_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Members Key", "description": "S3 key to members.parquet (if saved)" }, "num_clusters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Clusters", "description": "Number of clusters found" }, "cluster_stats": { "anyOf": [ { "$ref": "#/components/schemas/ClusterStats" }, { "type": "null" } ], "description": "Clustering quality metrics" }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "Clustering job status", "default": "PENDING" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "Associated task ID for clustering job" }, "last_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Run Id", "description": "Run ID of the most recent successful clustering execution. Used to retrieve execution results." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the cluster was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the cluster was last updated" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Additional user-defined metadata for the cluster" } }, "type": "object", "title": "ClusterModel", "description": "Cluster metadata stored in MongoDB.", "examples": [ { "cluster_name": "products_clip_hdbscan", "cluster_type": "vector", "collection_ids": [ "col_products_v1", "col_products_v2" ], "llm_labeling": { "enabled": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "description", "source_type": "payload" } ] }, "model_name": "gpt-4o-mini-2024-07-18", "provider": "openai" }, "vector_config": { "clustering_method": "hdbscan", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "hdbscan_parameters": { "min_cluster_size": 10, "min_samples": 5 }, "sample_size": 5000 } }, { "cluster_name": "video_multimodal_clustering", "cluster_type": "vector", "collection_ids": [ "col_videos_v1" ], "llm_labeling": { "enabled": true, "include_keywords": true, "include_summary": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "title", "source_type": "payload" }, { "input_key": "video_url", "path": "video_url", "source_type": "payload" } ] }, "model_name": "gemini-2.5-flash-lite", "provider": "google" }, "vector_config": { "clustering_method": "hdbscan", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "hdbscan_parameters": { "min_cluster_size": 5, "min_samples": 3 }, "sample_size": 3000 } }, { "cluster_name": "image_multimodal_clustering", "cluster_type": "vector", "collection_ids": [ "col_images_v1" ], "llm_labeling": { "enabled": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "caption", "source_type": "payload" }, { "input_key": "image_url", "path": "image_url", "source_type": "payload" } ] }, "model_name": "gemini-2.5-flash-lite", "provider": "google" }, "vector_config": { "clustering_method": "kmeans", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "kmeans_parameters": { "n_clusters": 10 }, "sample_size": 2000 } }, { "attribute_config": { "attributes": [ "status" ], "hierarchical_grouping": true }, "cluster_name": "orders_group_by_status", "cluster_type": "attribute", "collection_ids": [ "col_orders_v1", "col_orders_v2", "col_orders_v3" ] } ] }, "ClusterOptions": { "properties": { "preserve_cluster_ids": { "type": "boolean", "title": "Preserve Cluster Ids", "description": "Keep same cluster IDs in target", "default": true }, "preserve_assignments": { "type": "boolean", "title": "Preserve Assignments", "description": "Keep cluster_id in documents", "default": true }, "migrate_artifacts": { "type": "boolean", "title": "Migrate Artifacts", "description": "Copy parquet artifacts from S3", "default": true }, "preserve_centroids": { "type": "boolean", "title": "Preserve Centroids", "description": "Keep centroid collections", "default": true }, "recompute_clusters": { "type": "boolean", "title": "Recompute Clusters", "description": "Recompute clusters instead of copying", "default": false } }, "type": "object", "title": "ClusterOptions", "description": "Options for cluster migration." }, "ClusterStats": { "properties": { "num_clusters": { "type": "integer", "title": "Num Clusters" }, "noise_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Noise Points", "description": "Number of noise points (for DBSCAN, etc.)" }, "silhouette_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Silhouette Score", "description": "Silhouette score (-1 to 1, higher is better)" }, "extra": { "additionalProperties": true, "type": "object", "title": "Extra" } }, "type": "object", "required": [ "num_clusters" ], "title": "ClusterStats", "description": "Basic clustering quality metrics." }, "ClusterType": { "type": "string", "enum": [ "vector", "attribute" ], "title": "ClusterType", "description": "Type of clustering to perform.\n\nDetermines the clustering approach:\n- vector: Cluster documents by embedding similarity (semantic clustering)\n- attribute: Cluster documents by metadata attributes (business logic clustering)\n\nUse Cases:\n vector:\n - Group semantically similar content\n - Find content with similar meaning\n - Organize by topic/theme\n - Requires vector embeddings\n\n attribute:\n - Group by business attributes (category, brand, status, etc.)\n - Organize by explicit metadata\n - Create hierarchical groupings\n - No embeddings required" }, "ClusteringAlgorithm": { "type": "string", "enum": [ "kmeans", "dbscan", "hdbscan", "agglomerative", "spectral", "gaussian_mixture", "mean_shift", "optics", "leiden", "evoc", "attribute_based", "auto" ], "title": "ClusteringAlgorithm", "description": "Supported clustering algorithms.\n\nTwo types of clustering are available:\n1. Vector-based: Clusters documents by embedding similarity\n2. Attribute-based: Clusters documents by metadata attributes\n\nVector-based algorithms (require feature_vector):\n - kmeans: Partitions data into K clusters by minimizing within-cluster variance\n - dbscan: Density-based clustering, finds clusters of arbitrary shape\n - hdbscan: Hierarchical DBSCAN, auto-determines number of clusters\n - agglomerative: Hierarchical clustering using linkage criteria\n - spectral: Uses graph theory to find clusters\n - gaussian_mixture: Probabilistic model assuming Gaussian distributions\n - mean_shift: Finds clusters by locating density maxima\n - optics: Ordering points to identify clustering structure\n - leiden: Community detection on a kNN graph (fast at scale, auto cluster\n count via resolution; skips the UMAP step that dominates KMeans)\n - evoc: Embedding Vector Oriented Clustering (Tutte Institute) \u2014 built\n for embeddings, discovers the cluster count automatically, less\n parameter-sensitive than HDBSCAN and scales roughly linearly\n\nAttribute-based algorithm (requires attribute_config):\n - attribute_based: Groups documents by metadata attributes (e.g., category, brand)" }, "ClusteringEnrichmentResponse": { "properties": { "processed": { "type": "integer", "title": "Processed", "description": "Number of processed points" }, "enriched": { "type": "integer", "title": "Enriched", "description": "Number of enriched points" }, "failed": { "type": "integer", "title": "Failed", "description": "Number of failed points" }, "batches": { "type": "integer", "title": "Batches", "description": "Batches processed" } }, "type": "object", "required": [ "processed", "enriched", "failed", "batches" ], "title": "ClusteringEnrichmentResponse", "description": "Response after applying clustering enrichment." }, "CollectionDetail": { "properties": { "collection_id": { "type": "string", "title": "Collection Id", "description": "Collection identifier" }, "collection_name": { "type": "string", "title": "Collection Name", "description": "Human-readable collection name" }, "document_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Document Count", "description": "Number of documents in the collection" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "description": "Whether the collection is active" }, "last_indexed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Indexed At", "description": "When the collection was last indexed" } }, "type": "object", "required": [ "collection_id", "collection_name" ], "title": "CollectionDetail", "description": "Detailed information about a collection referenced by a retriever." }, "CollectionDiagnostic": { "properties": { "collection_id": { "type": "string", "title": "Collection Id", "description": "Collection ID" }, "collection_name": { "type": "string", "title": "Collection Name", "description": "Collection name" }, "document_count": { "type": "integer", "title": "Document Count", "description": "Number of documents in collection", "default": 0 }, "expected_documents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expected Documents", "description": "Expected document count" }, "status": { "type": "string", "title": "Status", "description": "Collection status (ready, processing, empty)" } }, "type": "object", "required": [ "collection_id", "collection_name", "status" ], "title": "CollectionDiagnostic", "description": "Diagnostic information for a collection." }, "CollectionExportRequest": { "properties": { "format": { "$ref": "#/components/schemas/ExportFormat", "description": "Export format: json (line-delimited), csv, or parquet (default).", "default": "parquet" }, "include_vectors": { "type": "boolean", "title": "Include Vectors", "description": "Whether to include vectors in the export. Vectors are exported to a separate file due to their large size. This significantly increases export time and file size.", "default": false }, "select_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Select Fields", "description": "Specific fields to include in the export. If not provided, all fields are exported. Supports dot notation for nested fields (e.g., 'metadata.title', 'metadata.author').", "examples": [ [ "document_id", "metadata.title", "metadata.category" ] ] }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "Filter conditions to export only matching documents. Uses LogicalOperator format (AND/OR/NOT) same as document listing." }, "sample_size": { "anyOf": [ { "type": "integer", "maximum": 1000000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Sample Size", "description": "Maximum number of documents to export. If not provided, exports all documents. Useful for testing exports or creating sample datasets." } }, "type": "object", "title": "CollectionExportRequest", "description": "Request model for exporting collection data.\n\n**Export Formats:**\n- **JSON**: Line-delimited JSON (JSONL) format, one document per line. Good for streaming and large files.\n- **CSV**: Comma-separated values. Best for tabular data analysis in spreadsheets.\n- **PARQUET**: Columnar format optimized for analytics. Best for large datasets and data pipelines.\n\n**Vector Export:**\nVectors are stored separately from document metadata due to their large size.\nWhen `include_vectors=True`, vectors are exported to a separate file with the naming convention:\n`{collection_name}_vectors.{format}`\n\n**Field Selection:**\nUse `select_fields` to export only specific fields, reducing file size for large collections.\nSupports dot notation for nested fields (e.g., \"metadata.title\").\n\n**Filtering:**\nApply filters to export a subset of documents. Uses the same LogicalOperator format\nas the documents list endpoint." }, "CollectionExportResponse": { "properties": { "download_url": { "type": "string", "title": "Download Url", "description": "Presigned URL for downloading the exported file. Valid for 1 hour." }, "s3_path": { "type": "string", "title": "S3 Path", "description": "Full S3 path where the export is stored (for internal reference)." }, "format": { "$ref": "#/components/schemas/ExportFormat", "description": "The format of the exported file." }, "document_count": { "type": "integer", "minimum": 0.0, "title": "Document Count", "description": "Number of documents included in the export." }, "file_size_bytes": { "type": "integer", "minimum": 0.0, "title": "File Size Bytes", "description": "Size of the exported file in bytes." }, "exported_at": { "type": "string", "format": "date-time", "title": "Exported At", "description": "Timestamp when the export was completed." }, "vectors_download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vectors Download Url", "description": "Presigned URL for downloading the vectors file (if include_vectors=True). Vectors are exported separately due to their large size." }, "vectors_s3_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vectors S3 Path", "description": "Full S3 path for the vectors file (if include_vectors=True)." } }, "type": "object", "required": [ "download_url", "s3_path", "format", "document_count", "file_size_bytes", "exported_at" ], "title": "CollectionExportResponse", "description": "Response model for collection export.\n\nContains the presigned URL for downloading the exported file.\nThe URL is valid for a limited time (typically 1 hour).", "examples": [ { "document_count": 10000, "download_url": "https://s3.amazonaws.com/bucket/org_xxx/ns_xxx/api_collections_export/col_xxx/v1/documents.parquet?...", "exported_at": "2024-01-15T10:30:00Z", "file_size_bytes": 5242880, "format": "parquet", "s3_path": "s3://bucket/org_xxx/ns_xxx/api_collections_export/col_xxx/v1/documents.parquet" } ] }, "CollectionFeatureDescriptor": { "properties": { "feature_address": { "type": "string", "title": "Feature Address", "description": "Fully qualified feature address" }, "feature_extractor_name": { "type": "string", "title": "Feature Extractor Name", "description": "Extractor name" }, "version": { "type": "string", "title": "Version", "description": "Extractor version" }, "vector_index": { "$ref": "#/components/schemas/VectorIndex", "description": "Vector index configuration (name, dimensions, type, distance, inference_name)" }, "primary": { "type": "boolean", "title": "Primary", "description": "True if this is the primary output (short address allowed)", "default": false } }, "type": "object", "required": [ "feature_address", "feature_extractor_name", "version", "vector_index" ], "title": "CollectionFeatureDescriptor", "description": "Descriptor for a collection's available feature using existing models/keys." }, "CollectionListStats": { "properties": { "total_documents": { "type": "integer", "title": "Total Documents", "description": "Total number of documents across all collections", "default": 0 }, "avg_documents_per_collection": { "type": "number", "title": "Avg Documents Per Collection", "description": "Average number of documents per collection", "default": 0.0 }, "collections_with_taxonomies": { "type": "integer", "title": "Collections With Taxonomies", "description": "Number of collections with taxonomy applications", "default": 0 }, "total_feature_extractors": { "type": "integer", "title": "Total Feature Extractors", "description": "Total number of feature extractors across all collections", "default": 0 }, "total_taxonomies": { "type": "integer", "title": "Total Taxonomies", "description": "Total number of taxonomy connections across all collections", "default": 0 }, "total_retrievers": { "type": "integer", "title": "Total Retrievers", "description": "Total number of retriever connections across all collections", "default": 0 } }, "type": "object", "title": "CollectionListStats", "description": "Aggregate statistics for a list of collections." }, "CollectionModel": { "properties": { "collection_id": { "type": "string", "title": "Collection Id", "description": "NOT REQUIRED (auto-generated). Unique identifier for this collection. Used for: API paths, document queries, pipeline references. Format: 'col_' prefix + 10 random alphanumeric characters. Stable after creation - use for all collection references.", "examples": [ "col_a1b2c3d4e5", "col_xyz789abc", "col_video_frames" ] }, "collection_name": { "type": "string", "maxLength": 100, "minLength": 3, "title": "Collection Name", "description": "REQUIRED. Human-readable name for the collection. Must be unique within the namespace. Used for: Display, lookups (can query by name or ID), organization. Format: Alphanumeric with underscores/hyphens, 3-100 characters. Examples: 'product_embeddings', 'video_frames', 'customer_documents'.", "examples": [ "video_frames", "product_embeddings", "customer_documents" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "NOT REQUIRED. Human-readable description of the collection's purpose. Use for: Documentation, team communication, UI display. Common pattern: Describe what the collection contains and what processing is applied.", "examples": [ "Video frames extracted at 1 FPS with CLIP embeddings", "Product catalog with image embeddings and metadata" ] }, "input_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Output" }, { "type": "null" } ], "description": "Auto-computed from source. Input schema defining fields available to the feature extractor. Source: bucket.bucket_schema (if source.type='bucket') OR upstream_collection.output_schema (if source.type='collection'). Determines: Which fields can be used in input_mappings and field_passthrough. This is the 'left side' of the transformation - what data goes IN. Format: BucketSchema with properties dict. Use for: Validating input_mappings, configuring field_passthrough.", "examples": [ { "properties": { "title": { "type": "string" }, "content": { "type": "text" } } }, { "properties": { "video": { "type": "video" }, "campaign_id": { "type": "string" } } } ] }, "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Output" }, { "type": "null" } ], "description": "Auto-computed at creation. Output schema defining fields in final documents. Computed as: field_passthrough fields + extractor output fields (deterministic). Known IMMEDIATELY when collection is created - no waiting for documents! This is the 'right side' of the transformation - what data comes OUT. Use for: Understanding document structure, building queries, schema validation. Example: {title (passthrough), embedding (extractor output)} = output_schema.", "examples": [ { "properties": { "title": { "type": "string" }, "text_extractor_v1_embedding": { "type": "array" } } }, { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } } ] }, "feature_extractor": { "$ref": "#/components/schemas/shared__collection__features__extractors__models__FeatureExtractorConfig-Output", "description": "REQUIRED. Single feature extractor configuration for this collection. Defines: extractor name/version, input_mappings, field_passthrough, parameters. Task 9 change: ONE extractor per collection (previously supported multiple). For multiple extractors: Create multiple collections and use collection-to-collection pipelines. Use field_passthrough to include additional source fields beyond extractor outputs.", "examples": [ { "feature_extractor_name": "text_extractor", "field_passthrough": [ { "source_path": "title" } ], "input_mappings": { "text": "content" }, "version": "v1" } ] }, "source": { "$ref": "#/components/schemas/SourceConfig-Output", "description": "REQUIRED. Source configuration defining where data comes from. Type 'bucket': Process objects from one or more buckets (tier 1). Type 'collection': Process documents from upstream collection(s) (tier 2+). For multi-bucket sources, all buckets must have compatible schemas. For multi-collection sources, all collections must have compatible schemas. Determines input_schema and enables decomposition trees.", "examples": [ { "bucket_ids": [ "bkt_articles" ], "type": "bucket" }, { "bucket_ids": [ "bkt_us_products", "bkt_eu_products" ], "type": "bucket" }, { "collection_id": "col_video_frames", "type": "collection" }, { "collection_ids": [ "col_products_2023", "col_products_2024" ], "type": "collection" } ] }, "source_bucket_schemas": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/BucketSchema-Output" }, "type": "object" }, { "type": "null" } ], "title": "Source Bucket Schemas", "description": "NOT REQUIRED (auto-computed). Snapshot of bucket schemas at collection creation. Only populated for multi-bucket collections (source.type='bucket' with multiple bucket_ids). Key: bucket_id, Value: BucketSchema at time of collection creation. Used for: Schema compatibility validation, document lineage, debugging. Schema snapshot is immutable - bucket schema changes after collection creation do not affect this. Single-bucket collections may omit this field (schema in input_schema is sufficient).", "examples": [ null, { "bkt_eu_products": { "properties": { "image": { "type": "image" }, "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "image", "title" ] }, "bkt_us_products": { "properties": { "image": { "type": "image" }, "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "image", "title" ] } } ] }, "source_lineage": { "items": { "$ref": "#/components/schemas/SingleLineageEntry" }, "type": "array", "title": "Source Lineage", "description": "NOT REQUIRED (auto-computed). Lineage chain showing complete processing history. Each entry contains: source_config, feature_extractor, output_schema for one tier. Length indicates processing depth (1 = tier 1, 2 = tier 2, etc.). Use for: Understanding multi-tier pipelines, visualizing decomposition trees.", "examples": [ [], [ { "output_schema": {}, "source_config": { "bucket_id": "bkt_videos", "type": "bucket" } } ] ] }, "vector_indexes": { "items": {}, "type": "array", "title": "Vector Indexes", "description": "NOT REQUIRED (auto-computed from extractor). Vector indexes for semantic search. Populated from feature_extractor.required_vector_indexes. Defines: Which embeddings are indexed, dimensions, distance metrics. Use for: Understanding search capabilities, debugging vector queries.", "examples": [ [], [ { "distance": "cosine", "name": "text_extractor_v1_embedding", "size": 1024 } ] ] }, "payload_indexes": { "items": {}, "type": "array", "title": "Payload Indexes", "description": "NOT REQUIRED (auto-computed from extractor + namespace). Payload indexes for filtering. Enables efficient filtering on metadata fields, timestamps, IDs. Populated from: extractor requirements + namespace defaults. Use for: Understanding which fields support fast filtering.", "examples": [ [], [ { "field_name": "collection_id", "type": "keyword" } ] ] }, "embedding_task": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embedding Task", "description": "Override the embedding task hint for instruction-aware models (E5, Gemini). Defaults to 'retrieval_document' for indexing pipelines. Values: retrieval_document, retrieval_query, semantic_similarity, classification, clustering. Applied to all task-aware embedding models in this collection's extractor pipeline." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "NOT REQUIRED (defaults to True). Whether the collection accepts new documents. False: Collection exists but won't process new objects. True: Active and processing. Use for: Temporarily disabling collections without deletion.", "default": true, "examples": [ true, false ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "NOT REQUIRED. Additional user-defined metadata for the collection. Arbitrary key-value pairs for custom organization, tracking, configuration. Not used by the platform - purely for user purposes. Common uses: team ownership, project tags, deployment environment.", "examples": [ { "environment": "production", "project": "Q4_campaign", "team": "data-science" }, null ] }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/CollectionScheduleConfig" }, { "type": "null" } ], "description": "NOT REQUIRED. Schedule configuration for automatic re-processing. When set, a COLLECTION_TRIGGER trigger is created and linked to this collection." }, "trigger_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Id", "description": "NOT REQUIRED. ID of the linked trigger for scheduled re-processing. Automatically set when a schedule is configured." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp when the collection was created. Automatically set by the system when the collection is first saved to the database." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Timestamp when the collection was last updated. Automatically updated by the system whenever the collection is modified." }, "lifecycle_state": { "type": "string", "title": "Lifecycle State", "description": "Storage lifecycle state: 'active' (Qdrant + S3), 'cold' (S3 only), 'archived' (metadata only). Managed via lifecycle API.", "default": "active" }, "s3_vector_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "S3 Vector Index", "description": "S3 Vectors index name for this collection (e.g. 'col_{collection_id}')." }, "last_lifecycle_transition": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Lifecycle Transition", "description": "Timestamp of the most recent lifecycle state change." }, "tiering_rules": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TieringRule" }, "type": "array" }, { "type": "null" } ], "title": "Tiering Rules", "description": "Automatic storage tiering rules (not enforced in V1)." }, "document_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Document Count", "description": "APPROXIMATE number of documents in the collection. This is NOT a stored counter maintained on every write \u2014 read endpoints DERIVE it from a live MVS count that is cached (~45s) and approximate (exact=False), so it can differ by a few from an exact documents/list enumeration and can lag very recent writes by the cache window. Use it for sorting/filtering and rough display; for an authoritative count, enumerate via documents/list. Do NOT treat a small document_count-vs-documents gap as row loss (BACKE-2988).", "default": 0, "examples": [ 0, 100, 50000 ] }, "schema_version": { "type": "integer", "title": "Schema Version", "description": "Version number for the output_schema. Increments automatically when schema is updated via document sampling. Used to track schema evolution and trigger downstream collection schema updates.", "default": 1 }, "last_schema_sync": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Schema Sync", "description": "Timestamp of last automatic schema sync from document sampling. Used to debounce schema updates (prevents thrashing)." }, "schema_sync_enabled": { "type": "boolean", "title": "Schema Sync Enabled", "description": "Whether automatic schema discovery and sync is enabled for this collection. When True, schema is periodically updated by sampling documents. When False, schema remains fixed at creation time.", "default": true }, "document_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Document Schema", "description": "NOT REQUIRED. JSON Schema for validating documents on create/update. When set with schema_validation='strict', non-conforming documents are rejected (422). When set with schema_validation='warn', violations are recorded but document is accepted. Schema follows JSON Schema draft-07 format. Only validates user-defined fields (system fields like _internal, collection_id, document_id are excluded from validation).", "examples": [ null, { "additionalProperties": true, "properties": { "title": { "maxLength": 200, "type": "string" }, "price": { "minimum": 0, "type": "number" }, "status": { "enum": [ "active", "draft", "archived" ], "type": "string" } }, "required": [ "title", "price" ], "type": "object" } ] }, "schema_validation": { "type": "string", "enum": [ "strict", "warn", "off" ], "title": "Schema Validation", "description": "Document schema validation mode. 'strict': reject non-conforming documents with 422. 'warn': accept but attach _schema_violations field to the document. 'off': no validation (default, preserves current behavior).", "default": "off", "examples": [ "off", "strict", "warn" ] }, "taxonomy_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaxonomyApplicationConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Taxonomy Applications", "description": "NOT REQUIRED. List of taxonomies to apply to documents in this collection. Each entry specifies: taxonomy_id, optional target_collection_id, optional filters. Enrichments are materialized (persisted to documents) during ingestion. Empty/null if no taxonomies attached. Use for: Categorization, hierarchical classification.", "examples": [ null, [ { "execution_mode": "materialize", "taxonomy_id": "tax_categories" }, { "execution_mode": "materialize", "taxonomy_id": "tax_brands" } ] ] }, "cluster_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ClusterApplicationConfig" }, "type": "array" }, { "type": "null" } ], "title": "Cluster Applications", "description": "NOT REQUIRED. List of clusters to automatically execute when batch processing completes. Each entry specifies: cluster_id, auto_execute_on_batch, min_document_threshold, cooldown_seconds. Clusters enrich source documents with cluster assignments (cluster_id, cluster_label, etc.). Empty/null if no clusters attached. Use for: Segmentation, grouping, pattern discovery.", "examples": [ null, [ { "auto_execute_on_batch": true, "cluster_id": "clust_product_categories", "cooldown_seconds": 3600, "min_document_threshold": 100 } ] ] }, "alert_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AlertApplicationConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Alert Applications", "description": "NOT REQUIRED. List of alerts to automatically execute when documents are ingested. Each entry specifies: alert_id, execution_mode, input_mappings, execution_phase, priority. Alerts run retrievers on ingested documents and send notifications when matches are found. Empty/null if no alerts attached. Use for: Content monitoring, safety detection, compliance alerts.", "examples": [ null, [ { "alert_id": "alt_safety_001", "execution_mode": "on_ingest", "execution_phase": 3, "input_mappings": [ { "input_key": "query_embedding", "source": { "path": "features.video_embedding", "source_type": "document_field" } } ], "priority": 100 } ] ] }, "retriever_enrichments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RetrieverEnrichmentConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Retriever Enrichments", "description": "NOT REQUIRED. List of retriever enrichments to run on documents during post-processing. Each entry specifies: retriever_id, input_mappings, write_back_fields, execution_phase, priority. Retriever enrichments execute a retriever pipeline and write selected result fields back to documents. Empty/null if no enrichments attached. Use for: LLM classification, cross-collection joins, enrichment.", "examples": [ null, [ { "execution_phase": 4, "input_mappings": [ { "input_key": "query", "source": { "path": "title", "source_type": "document_field" } } ], "priority": 0, "retriever_id": "ret_classifier_001", "write_back_fields": [ { "mode": "first", "source_field": "category", "target_field": "_enrichment_category" } ] } ] ] } }, "type": "object", "required": [ "collection_name", "feature_extractor", "source" ], "title": "CollectionModel", "description": "Collection model with single feature extractor and deterministic schema.\n\nCollections are processing pipelines that transform source data (from buckets or\nother collections) into searchable documents with features. Each collection\nrepresents ONE transformation step with ONE feature extractor.\n\nKey Concepts:\n - Input Schema: What goes IN (from bucket or upstream collection)\n - Feature Extractor: The transformation logic (text embedding, video processing, etc.)\n - Field Passthrough: User-selected source fields to include in output\n - Output Schema: What comes OUT (field_passthrough + extractor outputs)\n\nArchitecture (Task 9):\n - ONE feature extractor per collection (not a list)\n - output_schema computed at creation time (deterministic, no waiting)\n - Multiple extractors = multiple collections\n - Enables clean decomposition trees and clear lineage\n\nUse Cases:\n - Create embeddings from text/images/video\n - Build multi-tier pipelines (bucket \u2192 frames \u2192 scenes)\n - Apply feature extraction with metadata passthrough\n - Organize data processing into clear stages\n\nRequirements:\n - collection_name: REQUIRED, unique within namespace\n - source: REQUIRED, bucket or collection source\n - feature_extractor: REQUIRED, single extractor configuration\n - input_schema: Auto-computed from source (bucket_schema or upstream output_schema)\n - output_schema: Auto-computed at creation (field_passthrough + extractor output)", "examples": [ { "collection_id": "col_a1b2c3d4e5", "collection_name": "article_embeddings", "description": "Simple text collection: News articles with text embeddings from bucket source", "enabled": true, "feature_extractor": { "feature_extractor_name": "text_extractor", "field_passthrough": [ { "source_path": "title" } ], "input_mappings": { "text": "content" }, "version": "v1" }, "input_schema": { "properties": { "title": { "type": "string" }, "content": { "type": "text" } } }, "output_schema": { "properties": { "title": { "type": "string" }, "text_extractor_v1_embedding": { "type": "array" } } }, "source": { "bucket_id": "bkt_articles", "type": "bucket" } }, { "collection_id": "col_xyz789abc", "collection_name": "video_frames", "description": "Video frames: Extracted at 1 FPS with CLIP embeddings and campaign_id passthrough", "enabled": true, "feature_extractor": { "feature_extractor_name": "multimodal_extractor", "field_passthrough": [ { "source_path": "campaign_id" } ], "input_mappings": { "video": "video" }, "parameters": { "fps": 1 }, "version": "v1" }, "input_schema": { "properties": { "video": { "type": "video" }, "campaign_id": { "type": "string" } } }, "output_schema": { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } }, "source": { "bucket_id": "bkt_marketing_videos", "type": "bucket" } }, { "collection_id": "col_scenes_def", "collection_name": "detected_scenes", "description": "Tier 2 decomposition: Scenes detected from frame embeddings (collection source)", "enabled": true, "feature_extractor": { "feature_extractor_name": "scene_extractor", "field_passthrough": [ { "source_path": "campaign_id" } ], "input_mappings": { "embedding": "multimodal_extractor_v1_embedding" }, "version": "v1" }, "input_schema": { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } }, "output_schema": { "properties": { "campaign_id": { "type": "string" }, "scene_extractor_v1_embedding": { "type": "array" } } }, "source": { "collection_id": "col_video_frames", "type": "collection" } } ] }, "CollectionOverviewResponse": { "properties": { "collection_id": { "type": "string", "title": "Collection Id" }, "collection_name": { "type": "string", "title": "Collection Name" }, "total_documents": { "type": "integer", "title": "Total Documents" }, "documents_last_24h": { "type": "integer", "title": "Documents Last 24H" }, "documents_last_7d": { "type": "integer", "title": "Documents Last 7D" }, "avg_processing_time_ms": { "type": "number", "title": "Avg Processing Time Ms" }, "success_rate": { "type": "number", "title": "Success Rate" }, "active_taxonomies": { "type": "integer", "title": "Active Taxonomies" }, "active_clusters": { "type": "integer", "title": "Active Clusters" }, "last_indexed": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Indexed" } }, "type": "object", "required": [ "collection_id", "collection_name", "total_documents", "documents_last_24h", "documents_last_7d", "avg_processing_time_ms", "success_rate", "active_taxonomies", "active_clusters" ], "title": "CollectionOverviewResponse", "description": "Collection overview metrics." }, "CollectionResponse": { "properties": { "collection_id": { "type": "string", "title": "Collection Id", "description": "NOT REQUIRED (auto-generated). Unique identifier for this collection. Used for: API paths, document queries, pipeline references. Format: 'col_' prefix + 10 random alphanumeric characters. Stable after creation - use for all collection references.", "examples": [ "col_a1b2c3d4e5", "col_xyz789abc", "col_video_frames" ] }, "collection_name": { "type": "string", "maxLength": 100, "minLength": 3, "title": "Collection Name", "description": "REQUIRED. Human-readable name for the collection. Must be unique within the namespace. Used for: Display, lookups (can query by name or ID), organization. Format: Alphanumeric with underscores/hyphens, 3-100 characters. Examples: 'product_embeddings', 'video_frames', 'customer_documents'.", "examples": [ "video_frames", "product_embeddings", "customer_documents" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "NOT REQUIRED. Human-readable description of the collection's purpose. Use for: Documentation, team communication, UI display. Common pattern: Describe what the collection contains and what processing is applied.", "examples": [ "Video frames extracted at 1 FPS with CLIP embeddings", "Product catalog with image embeddings and metadata" ] }, "input_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Output" }, { "type": "null" } ], "description": "Auto-computed from source. Input schema defining fields available to the feature extractor. Source: bucket.bucket_schema (if source.type='bucket') OR upstream_collection.output_schema (if source.type='collection'). Determines: Which fields can be used in input_mappings and field_passthrough. This is the 'left side' of the transformation - what data goes IN. Format: BucketSchema with properties dict. Use for: Validating input_mappings, configuring field_passthrough.", "examples": [ { "properties": { "title": { "type": "string" }, "content": { "type": "text" } } }, { "properties": { "video": { "type": "video" }, "campaign_id": { "type": "string" } } } ] }, "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Output" }, { "type": "null" } ], "description": "Auto-computed at creation. Output schema defining fields in final documents. Computed as: field_passthrough fields + extractor output fields (deterministic). Known IMMEDIATELY when collection is created - no waiting for documents! This is the 'right side' of the transformation - what data comes OUT. Use for: Understanding document structure, building queries, schema validation. Example: {title (passthrough), embedding (extractor output)} = output_schema.", "examples": [ { "properties": { "title": { "type": "string" }, "text_extractor_v1_embedding": { "type": "array" } } }, { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } } ] }, "feature_extractor": { "$ref": "#/components/schemas/shared__collection__features__extractors__models__FeatureExtractorConfig-Output", "description": "REQUIRED. Single feature extractor configuration for this collection. Defines: extractor name/version, input_mappings, field_passthrough, parameters. Task 9 change: ONE extractor per collection (previously supported multiple). For multiple extractors: Create multiple collections and use collection-to-collection pipelines. Use field_passthrough to include additional source fields beyond extractor outputs.", "examples": [ { "feature_extractor_name": "text_extractor", "field_passthrough": [ { "source_path": "title" } ], "input_mappings": { "text": "content" }, "version": "v1" } ] }, "source": { "$ref": "#/components/schemas/SourceConfig-Output", "description": "REQUIRED. Source configuration defining where data comes from. Type 'bucket': Process objects from one or more buckets (tier 1). Type 'collection': Process documents from upstream collection(s) (tier 2+). For multi-bucket sources, all buckets must have compatible schemas. For multi-collection sources, all collections must have compatible schemas. Determines input_schema and enables decomposition trees.", "examples": [ { "bucket_ids": [ "bkt_articles" ], "type": "bucket" }, { "bucket_ids": [ "bkt_us_products", "bkt_eu_products" ], "type": "bucket" }, { "collection_id": "col_video_frames", "type": "collection" }, { "collection_ids": [ "col_products_2023", "col_products_2024" ], "type": "collection" } ] }, "source_bucket_schemas": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/BucketSchema-Output" }, "type": "object" }, { "type": "null" } ], "title": "Source Bucket Schemas", "description": "NOT REQUIRED (auto-computed). Snapshot of bucket schemas at collection creation. Only populated for multi-bucket collections (source.type='bucket' with multiple bucket_ids). Key: bucket_id, Value: BucketSchema at time of collection creation. Used for: Schema compatibility validation, document lineage, debugging. Schema snapshot is immutable - bucket schema changes after collection creation do not affect this. Single-bucket collections may omit this field (schema in input_schema is sufficient).", "examples": [ null, { "bkt_eu_products": { "properties": { "image": { "type": "image" }, "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "image", "title" ] }, "bkt_us_products": { "properties": { "image": { "type": "image" }, "title": { "type": "string" }, "price": { "type": "number" } }, "required": [ "image", "title" ] } } ] }, "source_lineage": { "items": { "$ref": "#/components/schemas/SingleLineageEntry" }, "type": "array", "title": "Source Lineage", "description": "NOT REQUIRED (auto-computed). Lineage chain showing complete processing history. Each entry contains: source_config, feature_extractor, output_schema for one tier. Length indicates processing depth (1 = tier 1, 2 = tier 2, etc.). Use for: Understanding multi-tier pipelines, visualizing decomposition trees.", "examples": [ [], [ { "output_schema": {}, "source_config": { "bucket_id": "bkt_videos", "type": "bucket" } } ] ] }, "vector_indexes": { "items": {}, "type": "array", "title": "Vector Indexes", "description": "NOT REQUIRED (auto-computed from extractor). Vector indexes for semantic search. Populated from feature_extractor.required_vector_indexes. Defines: Which embeddings are indexed, dimensions, distance metrics. Use for: Understanding search capabilities, debugging vector queries.", "examples": [ [], [ { "distance": "cosine", "name": "text_extractor_v1_embedding", "size": 1024 } ] ] }, "payload_indexes": { "items": {}, "type": "array", "title": "Payload Indexes", "description": "NOT REQUIRED (auto-computed from extractor + namespace). Payload indexes for filtering. Enables efficient filtering on metadata fields, timestamps, IDs. Populated from: extractor requirements + namespace defaults. Use for: Understanding which fields support fast filtering.", "examples": [ [], [ { "field_name": "collection_id", "type": "keyword" } ] ] }, "embedding_task": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embedding Task", "description": "Override the embedding task hint for instruction-aware models (E5, Gemini). Defaults to 'retrieval_document' for indexing pipelines. Values: retrieval_document, retrieval_query, semantic_similarity, classification, clustering. Applied to all task-aware embedding models in this collection's extractor pipeline." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "NOT REQUIRED (defaults to True). Whether the collection accepts new documents. False: Collection exists but won't process new objects. True: Active and processing. Use for: Temporarily disabling collections without deletion.", "default": true, "examples": [ true, false ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "NOT REQUIRED. Additional user-defined metadata for the collection. Arbitrary key-value pairs for custom organization, tracking, configuration. Not used by the platform - purely for user purposes. Common uses: team ownership, project tags, deployment environment.", "examples": [ { "environment": "production", "project": "Q4_campaign", "team": "data-science" }, null ] }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/CollectionScheduleConfig" }, { "type": "null" } ], "description": "NOT REQUIRED. Schedule configuration for automatic re-processing. When set, a COLLECTION_TRIGGER trigger is created and linked to this collection." }, "trigger_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Id", "description": "NOT REQUIRED. ID of the linked trigger for scheduled re-processing. Automatically set when a schedule is configured." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp when the collection was created. Automatically set by the system when the collection is first saved to the database." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Timestamp when the collection was last updated. Automatically updated by the system whenever the collection is modified." }, "lifecycle_state": { "type": "string", "title": "Lifecycle State", "description": "Storage lifecycle state: 'active' (Qdrant + S3), 'cold' (S3 only), 'archived' (metadata only). Managed via lifecycle API.", "default": "active" }, "s3_vector_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "S3 Vector Index", "description": "S3 Vectors index name for this collection (e.g. 'col_{collection_id}')." }, "last_lifecycle_transition": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Lifecycle Transition", "description": "Timestamp of the most recent lifecycle state change." }, "tiering_rules": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TieringRule" }, "type": "array" }, { "type": "null" } ], "title": "Tiering Rules", "description": "Automatic storage tiering rules (not enforced in V1)." }, "document_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Document Count", "description": "Number of documents in the collection" }, "schema_version": { "type": "integer", "title": "Schema Version", "description": "Version number for the output_schema. Increments automatically when schema is updated via document sampling. Used to track schema evolution and trigger downstream collection schema updates.", "default": 1 }, "last_schema_sync": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Schema Sync", "description": "Timestamp of last automatic schema sync from document sampling. Used to debounce schema updates (prevents thrashing)." }, "schema_sync_enabled": { "type": "boolean", "title": "Schema Sync Enabled", "description": "Whether automatic schema discovery and sync is enabled for this collection. When True, schema is periodically updated by sampling documents. When False, schema remains fixed at creation time.", "default": true }, "document_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Document Schema", "description": "NOT REQUIRED. JSON Schema for validating documents on create/update. When set with schema_validation='strict', non-conforming documents are rejected (422). When set with schema_validation='warn', violations are recorded but document is accepted. Schema follows JSON Schema draft-07 format. Only validates user-defined fields (system fields like _internal, collection_id, document_id are excluded from validation).", "examples": [ null, { "additionalProperties": true, "properties": { "title": { "maxLength": 200, "type": "string" }, "price": { "minimum": 0, "type": "number" }, "status": { "enum": [ "active", "draft", "archived" ], "type": "string" } }, "required": [ "title", "price" ], "type": "object" } ] }, "schema_validation": { "type": "string", "enum": [ "strict", "warn", "off" ], "title": "Schema Validation", "description": "Document schema validation mode. 'strict': reject non-conforming documents with 422. 'warn': accept but attach _schema_violations field to the document. 'off': no validation (default, preserves current behavior).", "default": "off", "examples": [ "off", "strict", "warn" ] }, "taxonomy_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaxonomyApplicationConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Taxonomy Applications", "description": "NOT REQUIRED. List of taxonomies to apply to documents in this collection. Each entry specifies: taxonomy_id, optional target_collection_id, optional filters. Enrichments are materialized (persisted to documents) during ingestion. Empty/null if no taxonomies attached. Use for: Categorization, hierarchical classification.", "examples": [ null, [ { "execution_mode": "materialize", "taxonomy_id": "tax_categories" }, { "execution_mode": "materialize", "taxonomy_id": "tax_brands" } ] ] }, "cluster_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ClusterApplicationConfig" }, "type": "array" }, { "type": "null" } ], "title": "Cluster Applications", "description": "NOT REQUIRED. List of clusters to automatically execute when batch processing completes. Each entry specifies: cluster_id, auto_execute_on_batch, min_document_threshold, cooldown_seconds. Clusters enrich source documents with cluster assignments (cluster_id, cluster_label, etc.). Empty/null if no clusters attached. Use for: Segmentation, grouping, pattern discovery.", "examples": [ null, [ { "auto_execute_on_batch": true, "cluster_id": "clust_product_categories", "cooldown_seconds": 3600, "min_document_threshold": 100 } ] ] }, "alert_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AlertApplicationConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Alert Applications", "description": "NOT REQUIRED. List of alerts to automatically execute when documents are ingested. Each entry specifies: alert_id, execution_mode, input_mappings, execution_phase, priority. Alerts run retrievers on ingested documents and send notifications when matches are found. Empty/null if no alerts attached. Use for: Content monitoring, safety detection, compliance alerts.", "examples": [ null, [ { "alert_id": "alt_safety_001", "execution_mode": "on_ingest", "execution_phase": 3, "input_mappings": [ { "input_key": "query_embedding", "source": { "path": "features.video_embedding", "source_type": "document_field" } } ], "priority": 100 } ] ] }, "retriever_enrichments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RetrieverEnrichmentConfig-Output" }, "type": "array" }, { "type": "null" } ], "title": "Retriever Enrichments", "description": "NOT REQUIRED. List of retriever enrichments to run on documents during post-processing. Each entry specifies: retriever_id, input_mappings, write_back_fields, execution_phase, priority. Retriever enrichments execute a retriever pipeline and write selected result fields back to documents. Empty/null if no enrichments attached. Use for: LLM classification, cross-collection joins, enrichment.", "examples": [ null, [ { "execution_phase": 4, "input_mappings": [ { "input_key": "query", "source": { "path": "title", "source_type": "document_field" } } ], "priority": 0, "retriever_id": "ret_classifier_001", "write_back_fields": [ { "mode": "first", "source_field": "category", "target_field": "_enrichment_category" } ] } ] ] }, "vector_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Vector Count", "description": "Total number of vector entries across all documents in this collection. Computed as document_count * number_of_vector_indexes. Each document stores one vector per configured vector index (e.g. a collection with 1 embedding produces 1 vector per document)." }, "taxonomy_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Taxonomy Count", "description": "Number of taxonomies connected to this collection" }, "retriever_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retriever Count", "description": "Number of retrievers connected to this collection" } }, "type": "object", "required": [ "collection_name", "feature_extractor", "source" ], "title": "CollectionResponse", "description": "Response model for collection endpoints.", "examples": [ { "collection_id": "col_a1b2c3d4e5", "collection_name": "article_embeddings", "description": "Simple text collection: News articles with text embeddings from bucket source", "enabled": true, "feature_extractor": { "feature_extractor_name": "text_extractor", "field_passthrough": [ { "source_path": "title" } ], "input_mappings": { "text": "content" }, "version": "v1" }, "input_schema": { "properties": { "title": { "type": "string" }, "content": { "type": "text" } } }, "output_schema": { "properties": { "title": { "type": "string" }, "text_extractor_v1_embedding": { "type": "array" } } }, "source": { "bucket_id": "bkt_articles", "type": "bucket" } }, { "collection_id": "col_xyz789abc", "collection_name": "video_frames", "description": "Video frames: Extracted at 1 FPS with CLIP embeddings and campaign_id passthrough", "enabled": true, "feature_extractor": { "feature_extractor_name": "multimodal_extractor", "field_passthrough": [ { "source_path": "campaign_id" } ], "input_mappings": { "video": "video" }, "parameters": { "fps": 1 }, "version": "v1" }, "input_schema": { "properties": { "video": { "type": "video" }, "campaign_id": { "type": "string" } } }, "output_schema": { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } }, "source": { "bucket_id": "bkt_marketing_videos", "type": "bucket" } }, { "collection_id": "col_scenes_def", "collection_name": "detected_scenes", "description": "Tier 2 decomposition: Scenes detected from frame embeddings (collection source)", "enabled": true, "feature_extractor": { "feature_extractor_name": "scene_extractor", "field_passthrough": [ { "source_path": "campaign_id" } ], "input_mappings": { "embedding": "multimodal_extractor_v1_embedding" }, "version": "v1" }, "input_schema": { "properties": { "campaign_id": { "type": "string" }, "multimodal_extractor_v1_embedding": { "type": "array" } } }, "output_schema": { "properties": { "campaign_id": { "type": "string" }, "scene_extractor_v1_embedding": { "type": "array" } } }, "source": { "collection_id": "col_video_frames", "type": "collection" } } ] }, "CollectionScheduleConfig": { "properties": { "trigger_type": { "type": "string", "title": "Trigger Type", "description": "Schedule type: 'cron' or 'interval'", "examples": [ "cron", "interval" ] }, "schedule_config": { "additionalProperties": true, "type": "object", "title": "Schedule Config", "description": "Schedule configuration. For cron: {cron_expression, timezone}. For interval: {interval_seconds, start_immediately}.", "examples": [ { "cron_expression": "0 2 * * *", "timezone": "UTC" }, { "interval_seconds": 21600, "start_immediately": false } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable description of the schedule." } }, "type": "object", "required": [ "trigger_type", "schedule_config" ], "title": "CollectionScheduleConfig", "description": "Schedule configuration for automatic collection re-processing.\n\nAttaches a cron or interval schedule to a collection, which creates\na COLLECTION_TRIGGER trigger behind the scenes. This is a DX convenience\nso users don't need to create triggers manually.\n\nExamples:\n Daily re-crawl at 2am UTC:\n {\"trigger_type\": \"cron\", \"schedule_config\": {\"cron_expression\": \"0 2 * * *\"}}\n\n Every 6 hours:\n {\"trigger_type\": \"interval\", \"schedule_config\": {\"interval_seconds\": 21600}}" }, "ColumnSource": { "properties": { "type": { "type": "string", "const": "column", "title": "Type", "description": "Source type identifier. Must be 'column' for database columns.", "default": "column" }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The column name to extract from. Case handling depends on the database. Snowflake: case-insensitive (defaults to uppercase). PostgreSQL: case-sensitive unless quoted. Column must exist in the source table/view.", "examples": [ "category", "CUSTOMER_TYPE", "metadata_json", "image_url" ] } }, "type": "object", "required": [ "name" ], "title": "ColumnSource", "description": "Extract value from a database column (Snowflake, PostgreSQL, etc.).\n\nFor database sync sources, maps a column from the source table/view\nto a bucket schema field. Column handling varies by database.\n\nProvider Compatibility: Snowflake, PostgreSQL (future), BigQuery (future)\n\nExample Snowflake table:\n CREATE TABLE CUSTOMERS (\n ID VARCHAR, NAME VARCHAR, CATEGORY VARCHAR,\n CREATED_AT TIMESTAMP, PROFILE_IMAGE_URL VARCHAR\n );\n\nExample mapping:\n {\"type\": \"column\", \"name\": \"CATEGORY\"} -> extracts the CATEGORY column value\n\nDatabase-Specific Notes:\n - Snowflake: Case-insensitive (internally uppercase), use unquoted names\n - PostgreSQL: Case-sensitive if quoted, defaults to lowercase\n - BigQuery: Case-sensitive\n\nAttributes:\n type: Must be \"column\" to identify this source type\n name: The column name to extract from" }, "ComponentsConfig": { "properties": { "show_hero": { "type": "boolean", "title": "Show Hero", "description": "Whether to show the hero section with title and description", "default": true }, "show_search": { "type": "boolean", "title": "Show Search", "description": "Whether to show search input fields", "default": true }, "show_filters": { "type": "boolean", "title": "Show Filters", "description": "Whether to show filters sidebar", "default": false }, "show_results_header": { "type": "boolean", "title": "Show Results Header", "description": "Whether to show the results header with count and sorting options", "default": true }, "result_layout": { "type": "string", "title": "Result Layout", "description": "Layout mode for results display", "default": "grid", "examples": [ "grid", "list", "masonry" ] }, "result_card": { "anyOf": [ { "$ref": "#/components/schemas/ResultCardProperties" }, { "type": "null" } ], "description": "Configuration for result card display" } }, "type": "object", "title": "ComponentsConfig", "description": "Configuration for UI components.", "examples": [ { "result_card": { "card_click_action": "viewDetails", "field_order": [ "title", "description" ], "layout": "vertical", "show_find_similar": true, "show_thumbnail": true }, "result_layout": "grid", "show_filters": false, "show_hero": true, "show_results_header": true, "show_search": true } ] }, "CompoundIndexPattern": { "properties": { "field_combination": { "items": { "type": "string" }, "type": "array", "title": "Field Combination", "description": "Fields used together" }, "combination_count": { "type": "integer", "title": "Combination Count", "description": "Number of times this combination was used" }, "avg_latency_ms": { "type": "number", "title": "Avg Latency Ms", "description": "Average latency for this combination" }, "p95_latency_ms": { "type": "number", "title": "P95 Latency Ms", "description": "95th percentile latency" } }, "type": "object", "required": [ "field_combination", "combination_count", "avg_latency_ms", "p95_latency_ms" ], "title": "CompoundIndexPattern", "description": "Pattern of fields commonly queried together." }, "CompoundIndexResponse": { "properties": { "namespace_id": { "type": "string", "title": "Namespace Id", "description": "Namespace ID analyzed" }, "time_range_days": { "type": "integer", "title": "Time Range Days", "description": "Number of days analyzed" }, "patterns": { "items": { "$ref": "#/components/schemas/CompoundIndexPattern" }, "type": "array", "title": "Patterns", "description": "Compound field patterns" }, "total_patterns": { "type": "integer", "title": "Total Patterns", "description": "Total patterns found" } }, "type": "object", "required": [ "namespace_id", "time_range_days", "patterns", "total_patterns" ], "title": "CompoundIndexResponse", "description": "Response for compound index patterns endpoint." }, "ComputeCostSummary": { "properties": { "cpu_hours": { "type": "number", "title": "Cpu Hours", "default": 0.0 }, "gpu_hours": { "type": "number", "title": "Gpu Hours", "default": 0.0 }, "base_cost_usd": { "type": "number", "title": "Base Cost Usd", "default": 0.0 }, "daily_breakdown": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Daily Breakdown" } }, "type": "object", "title": "ComputeCostSummary" }, "ComputeTier": { "type": "string", "enum": [ "shared", "dedicated_cpu", "dedicated_gpu" ], "title": "ComputeTier", "description": "Available compute tiers for namespace workloads.\n\nCompute tiers determine the infrastructure resources allocated to a namespace\nfor ingestion pipelines, clustering, and other data processing operations.\n\nTiers:\n SHARED: Multi-tenant infrastructure with dynamic resource allocation.\n - Best for: Development, testing, low-volume production workloads\n - Resources: Shared CPU and memory pool\n - Cost: Lowest cost option, pay-per-use credits\n - SLA: Best-effort availability\n\n DEDICATED_CPU: Single-tenant CPU compute nodes.\n - Best for: Production workloads requiring consistent performance\n - Resources: Reserved CPU cores and memory\n - Cost: Fixed monthly cost plus usage credits\n - SLA: 99.9% uptime guarantee\n\n DEDICATED_GPU: Single-tenant GPU-accelerated compute nodes.\n - Best for: Video processing, embedding generation, ML inference\n - Resources: Reserved GPU(s), CPU cores, and memory\n - Cost: Premium pricing, fixed monthly cost plus usage credits\n - SLA: 99.9% uptime guarantee\n\nExamples:\n - Use SHARED for development and staging environments\n - Use DEDICATED_CPU for production document processing pipelines\n - Use DEDICATED_GPU for large-scale video ingestion and analysis" }, "ConfidenceDistribution": { "properties": { "confidence_range": { "type": "string", "title": "Confidence Range", "description": "Confidence range (e.g., '0.8-0.9')" }, "count": { "type": "integer", "title": "Count" }, "percentage": { "type": "number", "title": "Percentage" } }, "type": "object", "required": [ "confidence_range", "count", "percentage" ], "title": "ConfidenceDistribution", "description": "Confidence score distribution bucket." }, "ConfidenceResponse": { "properties": { "taxonomy_id": { "type": "string", "title": "Taxonomy Id" }, "distribution": { "items": { "$ref": "#/components/schemas/ConfidenceDistribution" }, "type": "array", "title": "Distribution" }, "avg_confidence": { "type": "number", "title": "Avg Confidence" }, "low_confidence_count": { "type": "integer", "title": "Low Confidence Count", "description": "Count of assignments below 0.5 confidence" } }, "type": "object", "required": [ "taxonomy_id", "distribution", "avg_confidence", "low_confidence_count" ], "title": "ConfidenceResponse", "description": "Taxonomy confidence distribution response." }, "ConfirmModelUploadRequest": { "properties": { "etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Etag", "description": "S3 ETag from upload response for integrity check" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size Bytes", "description": "Expected file size for validation" } }, "type": "object", "title": "ConfirmModelUploadRequest", "description": "Request to confirm a model upload after S3 upload completes.\n\nOptional fields for integrity verification:\n- etag: S3 ETag returned from PUT response (recommended)\n- file_size_bytes: Expected file size for validation" }, "ConfirmModelUploadResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether upload and validation succeeded" }, "upload_id": { "type": "string", "title": "Upload Id", "description": "The upload ID" }, "model_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Id", "description": "Created model ID if successful" }, "validation_status": { "type": "string", "enum": [ "pending", "passed", "failed" ], "title": "Validation Status", "description": "Validation status" }, "validation_errors": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Validation Errors", "description": "Validation errors if any" }, "s3_archive_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "S3 Archive Url", "description": "S3 URL of the archive" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Additional status message" } }, "type": "object", "required": [ "success", "upload_id", "validation_status" ], "title": "ConfirmModelUploadResponse", "description": "Response from confirming a model upload." }, "ConfirmPaymentMethodRequest": { "properties": { "payment_method_id": { "type": "string", "title": "Payment Method Id", "description": "Stripe PaymentMethod ID from frontend", "examples": [ "pm_1ABC2DEF3GHI456" ] } }, "type": "object", "required": [ "payment_method_id" ], "title": "ConfirmPaymentMethodRequest", "description": "Request to confirm a payment method after collection." }, "ConfirmPaymentMethodResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether payment method was successfully confirmed", "default": true }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodInfo", "description": "Confirmed payment method details" }, "auto_billing_enabled": { "type": "boolean", "title": "Auto Billing Enabled", "description": "Whether auto-billing is now enabled" }, "billing_period_start": { "type": "string", "format": "date-time", "title": "Billing Period Start", "description": "When the current billing period started" } }, "type": "object", "required": [ "payment_method", "auto_billing_enabled", "billing_period_start" ], "title": "ConfirmPaymentMethodResponse", "description": "Response after confirming payment method." }, "ConfirmSubmissionRequest": { "properties": { "etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Etag", "description": "S3 ETag for integrity check" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size Bytes" } }, "type": "object", "title": "ConfirmSubmissionRequest" }, "ConfirmSubmissionResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "submission_id": { "type": "string", "title": "Submission Id" }, "status": { "type": "string", "title": "Status" }, "security_scan_passed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Security Scan Passed" }, "security_violations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Security Violations" }, "manifest_valid": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Manifest Valid" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "success", "submission_id", "status" ], "title": "ConfirmSubmissionResponse" }, "ConfirmUploadRequest": { "properties": { "etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Etag", "description": "S3 ETag returned from the upload. OPTIONAL but RECOMMENDED. After uploading to S3, the response includes an ETag header. Providing this ensures the file wasn't corrupted during upload. If provided and doesn't match S3's ETag, confirmation will fail with error. Format: Usually an MD5 hash, may be enclosed in quotes.", "examples": [ "d41d8cd98f00b204e9800998ecf8427e", "\"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\"" ] }, "file_size_bytes": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "File Size Bytes", "description": "Actual file size uploaded, in bytes. OPTIONAL but RECOMMENDED. If provided, will be validated against the actual S3 object size. Mismatch indicates upload corruption or network issues. If not provided, size validation is skipped.", "examples": [ 10485760, 52428800 ] }, "auto_submit_batch": { "type": "boolean", "title": "Auto Submit Batch", "description": "If true, automatically create AND submit a batch containing the newly created object after confirmation. The returned ``task_id`` will be the submitted batch's task id, and ``batch_id`` will be populated. Eliminates the need for separate POST /batches and POST /batches/{id}/submit calls during bulk ingest. Has no effect if ``create_object_on_confirm`` is false or the object is a duplicate. Defaults to false for backwards compatibility \u2014 existing flows that batch many objects into one submission still work.", "default": false } }, "type": "object", "title": "ConfirmUploadRequest", "description": "Request to confirm S3 upload completion and create bucket object.\n\n\u26a0\ufe0f THIS ENDPOINT IS REQUIRED AFTER UPLOADING TO S3!\n\nS3 presigned URLs have no callback mechanism - the API cannot detect when\nyour upload completes. You MUST call this endpoint to finalize the upload.\n\nWhy confirmation is required:\n - S3 doesn't notify us when uploads complete\n - We need to verify the file actually exists in S3\n - We need to create the bucket object\n - We need to update quotas and tracking\n\nThe system will:\n1. Verify the S3 object exists (HeadObject call)\n2. Validate ETag matches (if provided) - RECOMMENDED for integrity\n3. Validate file size matches (if provided)\n4. Create bucket object (default, unless create_object_on_confirm=false)\n5. Update upload status to COMPLETED\n\nIf you don't call confirm:\n - Upload stays in PENDING status\n - No bucket object is created\n - File is orphaned in S3", "examples": [ { "description": "Confirm with ETag for integrity verification (recommended)", "etag": "d41d8cd98f00b204e9800998ecf8427e", "file_size_bytes": 52428800 }, { "description": "Confirm with size only", "file_size_bytes": 10485760 }, { "auto_submit_batch": true, "description": "Auto-submit a batch after confirm (one-shot ingest)", "etag": "d41d8cd98f00b204e9800998ecf8427e", "file_size_bytes": 52428800 }, { "description": "Basic confirmation without validation (not recommended)" } ] }, "ConfirmUploadResponse": { "properties": { "upload_id": { "type": "string", "title": "Upload Id", "description": "Upload ID that was confirmed" }, "status": { "$ref": "#/components/schemas/TaskStatusEnum", "description": "Updated upload status (COMPLETED or PROCESSING)" }, "etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Etag", "description": "S3 ETag from uploaded object" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size Bytes", "description": "Actual file size from S3" }, "file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Hash", "description": "File content hash (from ETag)" }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Verified At", "description": "When verification completed" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "When upload completed" }, "object_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Object Id", "description": "Created bucket object ID (if create_object_on_confirm was true)" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "Task ID for async processing. Populated when auto_submit_batch=true (holds the submitted batch's first-tier task id) or when async=true." }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id", "description": "Batch ID created and submitted by auto_submit_batch=true. Use it to poll status via GET /v1/buckets/{id}/batches/{batch_id}." }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Confirmation message" } }, "type": "object", "required": [ "upload_id", "status" ], "title": "ConfirmUploadResponse", "description": "Response from upload confirmation.", "examples": [ { "completed_at": "2024-01-15T10:35:00Z", "description": "Synchronous confirmation with object creation", "etag": "d41d8cd98f00b204e9800998ecf8427e", "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "file_size_bytes": 52428800, "object_id": "obj_xyz789", "status": "COMPLETED", "upload_id": "upl_abc123", "verified_at": "2024-01-15T10:35:00Z" }, { "description": "Asynchronous confirmation", "message": "Upload confirmation is being processed in the background.", "status": "PROCESSING", "task_id": "task_xyz789", "upload_id": "upl_abc123" } ] }, "ConfirmationRequest": { "properties": { "approved": { "type": "boolean", "title": "Approved", "description": "True to approve, False to deny the action" } }, "type": "object", "required": [ "approved" ], "title": "ConfirmationRequest", "description": "Request to approve or deny a pending confirmation." }, "ConnectRepoRequest": { "properties": { "repo_url": { "type": "string", "title": "Repo Url", "description": "GitHub repository URL" }, "branch": { "type": "string", "title": "Branch", "description": "Branch to deploy from", "default": "main" }, "github_installation_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Github Installation Id", "description": "GitHub App installation ID" } }, "type": "object", "required": [ "repo_url" ], "title": "ConnectRepoRequest", "description": "Request to connect a GitHub repo for auto-deploy." }, "ConstantSource": { "properties": { "type": { "type": "string", "const": "constant", "title": "Type", "description": "Source type identifier. Must be 'constant' for static values.", "default": "constant" }, "value": { "title": "Value", "description": "The constant value to use for all objects. Can be any JSON-serializable value: string, number, boolean, array, object. Arrays are useful for tags, objects for structured metadata.", "examples": [ "production", 42, true, [ "tag1", "tag2" ], { "env": "prod" } ] } }, "type": "object", "required": [ "value" ], "title": "ConstantSource", "description": "Use a constant/static value for all synced objects.\n\nUseful for adding fixed metadata to all objects from a sync, such as:\n- Source system identifier\n- Environment tags\n- Default categories\n- Static labels\n\nProvider Compatibility: All providers\n\nExample mappings:\n {\"type\": \"constant\", \"value\": \"tigris-cdn\"} -> All objects get \"tigris-cdn\"\n {\"type\": \"constant\", \"value\": [\"tag1\", \"tag2\"]} -> All objects get this array\n {\"type\": \"constant\", \"value\": {\"env\": \"prod\"}} -> All objects get this object\n\nAttributes:\n type: Must be \"constant\" to identify this source type\n value: The constant value (any JSON-serializable type)" }, "CostBreakdown": { "properties": { "storage_percent": { "type": "number", "title": "Storage Percent", "description": "Storage cost percentage" }, "upload_percent": { "type": "number", "title": "Upload Percent", "description": "Upload cost percentage" }, "sync_percent": { "type": "number", "title": "Sync Percent", "description": "Sync cost percentage" }, "other_percent": { "type": "number", "title": "Other Percent", "description": "Other cost percentage" } }, "type": "object", "required": [ "storage_percent", "upload_percent", "sync_percent", "other_percent" ], "title": "CostBreakdown", "description": "Cost breakdown by category." }, "CostBreakdownSummary": { "properties": { "billing_month": { "type": "string", "title": "Billing Month" }, "cloud_provider": { "type": "string", "title": "Cloud Provider" }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data As Of" }, "data_delay_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data Delay Note" }, "cost_unavailable": { "type": "boolean", "title": "Cost Unavailable", "default": false }, "attribution_scope": { "type": "string", "title": "Attribution Scope", "default": "dedicated_k8s_ns" }, "total_cloud_cost_usd": { "type": "number", "title": "Total Cloud Cost Usd", "default": 0.0 }, "margin_pct": { "type": "number", "title": "Margin Pct", "default": 0.2 }, "total_margin_usd": { "type": "number", "title": "Total Margin Usd", "default": 0.0 }, "platform_fee_usd": { "type": "number", "title": "Platform Fee Usd", "default": 0.0 }, "platform_fee_billed_externally": { "type": "boolean", "title": "Platform Fee Billed Externally", "default": false }, "total_invoice_usd": { "type": "number", "title": "Total Invoice Usd", "default": 0.0 }, "categories": { "items": { "$ref": "#/components/schemas/CloudCostCategorySummary" }, "type": "array", "title": "Categories" }, "all_line_items": { "items": { "$ref": "#/components/schemas/CloudCostLineItem" }, "type": "array", "title": "All Line Items" } }, "type": "object", "required": [ "billing_month", "cloud_provider" ], "title": "CostBreakdownSummary" }, "CostRate": { "properties": { "unit": { "$ref": "#/components/schemas/CostUnit", "description": "The billing unit type" }, "credits_per_unit": { "type": "integer", "minimum": 1.0, "title": "Credits Per Unit", "description": "Number of credits charged per unit" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable description of what this rate covers" } }, "type": "object", "required": [ "unit", "credits_per_unit" ], "title": "CostRate", "description": "Cost rate for a specific billing unit.\n\nDefines how many credits are charged per unit of a specific type.\n\nExample:\n CostRate(\n unit=CostUnit.MINUTE,\n credits_per_unit=200,\n description=\"Video processing\"\n )\n # Means: 200 credits per minute of video" }, "CostUnit": { "type": "string", "enum": [ "minute", "image", "1k_tokens", "page", "face", "extraction" ], "title": "CostUnit", "description": "Standard billing units aligned with extractor input types.\n\nEach unit represents a measurable quantity that extractors process:\n- MINUTE: Video/audio duration in minutes\n- IMAGE: Per image processed\n- TOKENS_1K: Text tokens in thousands\n- PAGE: Document pages (PDF, etc.)\n- FACE: Detected faces in images/video\n- EXTRACTION: Flat per-operation cost" }, "CostsInfo": { "properties": { "tier": { "type": "integer", "maximum": 4.0, "minimum": 1.0, "title": "Tier", "description": "Cost tier (1-4): 1=SIMPLE, 2=MODERATE, 3=COMPLEX, 4=PREMIUM" }, "tier_label": { "type": "string", "title": "Tier Label", "description": "Human-readable tier label (SIMPLE, MODERATE, COMPLEX, PREMIUM)" }, "rates": { "items": { "$ref": "#/components/schemas/CostRate" }, "type": "array", "title": "Rates", "description": "List of cost rates for different input types this extractor processes" } }, "type": "object", "required": [ "tier", "tier_label", "rates" ], "title": "CostsInfo", "description": "Credit cost information for a feature extractor.\n\nDescribes the pricing tier and standardized cost rates for using this extractor.\nRates are defined using CostUnit types that align with extractor input types." }, "CovariateConfig": { "properties": { "field_path": { "type": "string", "title": "Field Path", "description": "Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')", "examples": [ "sender_domain", "metadata.word_count", "features.clip_embedding" ] }, "covariate_type": { "$ref": "#/components/schemas/CovariateType", "description": "Type of covariate determines analysis strategy (categorical/numeric/embedding/cluster)" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Human-readable name for this covariate in analytics results", "examples": [ "Sender Domain", "Word Count", "Visual Cluster" ] }, "binning_strategy": { "anyOf": [ { "type": "string", "enum": [ "quartiles", "deciles", "custom" ] }, { "type": "null" } ], "title": "Binning Strategy", "description": "How to bin numeric values for lift analysis (only used for NUMERIC type)", "default": "quartiles" }, "clustering_method": { "anyOf": [ { "type": "string", "enum": [ "kmeans", "hdbscan" ] }, { "type": "null" } ], "title": "Clustering Method", "description": "Clustering algorithm for embedding analysis (only used for EMBEDDING type)", "default": "kmeans" }, "n_clusters": { "anyOf": [ { "type": "integer", "maximum": 100.0, "minimum": 2.0 }, { "type": "null" } ], "title": "N Clusters", "description": "Number of clusters for embedding-based predictors (only used for EMBEDDING type)", "default": 10 } }, "type": "object", "required": [ "field_path", "covariate_type", "name" ], "title": "CovariateConfig", "description": "Configuration for a single covariate/predictor variable in step analytics.\n\nCovariates are used to identify which features predict conversion from one step\nto another. The system computes \"lift\" for each covariate value, showing whether\nit increases or decreases conversion likelihood.\n\nAttributes:\n field_path: JSONPath to the field in document or metadata (e.g., \"sender_domain\")\n covariate_type: How to analyze this covariate (categorical, numeric, embedding, cluster)\n name: Human-readable name for analytics results\n binning_strategy: For NUMERIC types, how to bin values (quartiles, deciles)\n clustering_method: For EMBEDDING types, algorithm to use (kmeans, hdbscan)\n n_clusters: For EMBEDDING types, number of clusters to create\n\nExamples:\n ```python\n # Analyze sender domains (categorical)\n CovariateConfig(\n field_path=\"sender_domain\",\n covariate_type=\"categorical\",\n name=\"Email Domain\"\n )\n\n # Analyze email length (numeric with quartile binning)\n CovariateConfig(\n field_path=\"word_count\",\n covariate_type=\"numeric\",\n name=\"Word Count\",\n binning_strategy=\"quartiles\"\n )\n\n # Analyze visual similarity (embedding clustering)\n CovariateConfig(\n field_path=\"features.clip_embedding\",\n covariate_type=\"embedding\",\n name=\"Visual Cluster\",\n clustering_method=\"kmeans\",\n n_clusters=10\n )\n ```" }, "CovariateType": { "type": "string", "enum": [ "categorical", "numeric", "embedding", "cluster_id" ], "title": "CovariateType", "description": "Type of covariate/predictor variable for conversion analysis.\n\nDifferent types enable different analysis strategies:\n- CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority)\n- NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price)\n- EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings)\n- CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster)\n\nExamples:\n ```python\n # Categorical: Which email domains convert better?\n CovariateConfig(field_path=\"sender_domain\", covariate_type=\"categorical\")\n\n # Numeric: Do longer emails convert faster?\n CovariateConfig(field_path=\"word_count\", covariate_type=\"numeric\")\n\n # Embedding: Do visually similar images follow similar paths?\n CovariateConfig(field_path=\"features.clip\", covariate_type=\"embedding\")\n\n # Cluster: Which topic clusters have highest conversion?\n CovariateConfig(field_path=\"metadata.topic_id\", covariate_type=\"cluster_id\")\n ```" }, "CrawlMode": { "type": "string", "enum": [ "deterministic", "semantic" ], "title": "CrawlMode", "description": "Mode for crawling web pages.\n\nValues:\n DETERMINISTIC: BFS crawl following all links up to max_depth\n SEMANTIC: LLM-guided crawl prioritizing pages relevant to crawl_goal" }, "CreateAlertRequest": { "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Human-readable name for the alert", "examples": [ "Safety Incident Detector", "Prohibited Content Alert" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description", "description": "Optional description of what this alert monitors", "examples": [ "Alerts when new videos match known safety incidents" ] }, "source": { "$ref": "#/components/schemas/AlertSource", "description": "Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)", "default": "retriever" }, "retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retriever Id", "description": "ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.", "examples": [ "ret_safety_search", "ret_prohibited_content" ] }, "trigger_on": { "$ref": "#/components/schemas/TriggerOn", "description": "source=retriever: fire on 'results' or 'no_results'", "default": "results" }, "system_condition": { "anyOf": [ { "$ref": "#/components/schemas/SystemCondition" }, { "type": "null" } ], "description": "Built-in data-plane condition to watch (source=system only)" }, "namespace_selector": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceSelector" }, { "type": "null" } ], "description": "Org-level namespace scoping (all vs selected)" }, "notification_config": { "$ref": "#/components/schemas/AlertNotificationConfig", "description": "How and where to send notifications when alert triggers" }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the alert is active and will execute", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional user-defined metadata for the alert" } }, "type": "object", "required": [ "name", "notification_config" ], "title": "CreateAlertRequest", "description": "Request model to create an alert.\n\nCreates a new alert that can be attached to collections to monitor\nfor matching content and send notifications when matches are found.\n\nNote: The alert references a retriever that contains all query logic\n(filters, min_score, limits, collection targeting). The alert's job\nis simply to run that retriever and notify if results exist.", "examples": [ { "description": "Alerts when new videos match known safety incidents", "enabled": true, "name": "Safety Incident Detector", "notification_config": { "channels": [ { "channel_id": "wh_safety_team", "channel_type": "webhook" } ], "include_matches": true, "include_scores": true }, "retriever_id": "ret_safety_search" } ] }, "CreateAnnotationRequest": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Document to annotate." }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id", "description": "Collection the document belongs to." }, "label": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Label", "description": "Decision label (e.g. 'approved', 'rejected', 'deferred')." }, "confidence": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Confidence", "description": "Human confidence (0.0\u20131.0)." }, "reasoning": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ], "title": "Reasoning", "description": "Why this decision was made." }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload", "description": "Structured payload (use-case-specific)." }, "retriever_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retriever Id" }, "execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Id" }, "stage_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage Name" } }, "type": "object", "required": [ "document_id", "label" ], "title": "CreateAnnotationRequest", "description": "Create a new annotation on a document." }, "CreateAppRequest": { "properties": { "slug": { "type": "string", "maxLength": 60, "minLength": 3, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "title": "Slug", "description": "URL-safe slug (globally unique, lowercase + hyphens). Becomes your URL: {slug}.mxp.co", "examples": [ "my-product-search", "brand-dashboard" ] }, "meta": { "$ref": "#/components/schemas/PageMeta", "description": "App metadata (title, logo, favicon)" }, "auth_config": { "anyOf": [ { "$ref": "#/components/schemas/AuthConfig-Input" }, { "type": "null" } ], "description": "End-user authentication. Set mode='clerk' for managed auth." }, "build_config": { "anyOf": [ { "$ref": "#/components/schemas/BuildConfig" }, { "type": "null" } ] }, "monitoring_config": { "anyOf": [ { "$ref": "#/components/schemas/MonitoringConfig" }, { "type": "null" } ] }, "is_active": { "type": "boolean", "title": "Is Active", "default": true }, "template": { "type": "string", "title": "Template", "default": "generic", "deprecated": true }, "sections": { "items": { "$ref": "#/components/schemas/SectionConfig" }, "type": "array", "title": "Sections", "deprecated": true }, "custom_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Html", "deprecated": true }, "hero": { "anyOf": [ { "$ref": "#/components/schemas/HeroConfig" }, { "type": "null" } ], "deprecated": true }, "theme": { "$ref": "#/components/schemas/ThemeConfig", "deprecated": true }, "seo": { "anyOf": [ { "$ref": "#/components/schemas/SEOConfig" }, { "type": "null" } ], "deprecated": true }, "stats": { "items": { "$ref": "#/components/schemas/StatItem" }, "type": "array", "title": "Stats", "deprecated": true }, "featured_gallery": { "anyOf": [ { "$ref": "#/components/schemas/FeaturedGalleryConfig-Input" }, { "type": "null" } ], "deprecated": true }, "tabs": { "items": { "$ref": "#/components/schemas/PageTab-Input" }, "type": "array", "title": "Tabs", "deprecated": true }, "password_secret_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password Secret Name", "deprecated": true } }, "type": "object", "required": [ "slug", "meta" ], "title": "CreateAppRequest", "description": "Request to create a new App.\n\nOnly ``slug`` and ``meta`` are required. After creation, deploy a zip\nbundle via ``POST /v1/apps/{app_id}/deploy``.\n\nLegacy page-builder fields (``template``, ``sections``, ``custom_html``,\n``hero``, ``theme``, ``seo``, ``stats``, ``featured_gallery``, ``tabs``,\n``password_secret_name``) are accepted for backward compatibility but\n**deprecated**. New apps should not use them.", "examples": [ { "meta": { "title": "Product Search" }, "slug": "my-product-search" }, { "auth_config": { "mode": "clerk" }, "meta": { "title": "Brand Dashboard" }, "slug": "brand-dashboard" } ] }, "CreateBatchRequest": { "properties": { "object_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ], "title": "Object Ids", "description": "List of object IDs to include in the batch. Objects must exist in the bucket where the batch is created. Minimum 1 object, no maximum limit. Mutually exclusive with 'filters'.", "examples": [ [ "object_789", "object_101" ], [ "obj_video_001", "obj_video_002", "obj_video_003" ] ] }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "Filter to select objects from the bucket. Resolved server-side into object IDs. Supports the same filter syntax as the object list endpoint. Mutually exclusive with 'object_ids'. Maximum 50,000 objects can be resolved from a filter." }, "collection_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Collection Ids", "description": "Optional list of collection IDs to process. When omitted, all collections sourced from this bucket (and their downstream dependencies) are auto-discovered. When provided, only these collections (plus their downstream dependencies) are included. Useful for submitting separate batches per collection to isolate failures. Accepts either 'collection_ids' or the shorthand 'collections'." }, "limit": { "anyOf": [ { "type": "integer", "maximum": 50000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Limit", "description": "Maximum number of objects to include when using filters. If omitted, all matching objects are included (up to 50,000)." }, "dedup_strategy": { "$ref": "#/components/schemas/DedupStrategy", "description": "Controls how objects that were already processed in prior batches are handled. Scoped to (bucket, collection): checks if the target collection already has documents from the same source object, regardless of which batch created them. 'skip' (default): Don't reprocess objects that already have documents. 'replace': Delete existing documents and reprocess from scratch. 'force': Process regardless, allowing duplicate documents.", "default": "skip", "examples": [ "skip", "replace", "force" ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/BatchMetadata" }, { "type": "null" } ], "description": "User-defined metadata for the batch. Has typed fields (campaign_id, source, tags, notes) and also accepts arbitrary extra keys. Persisted with the batch and returned in API responses.", "examples": [ { "campaign_id": "Q4_2025", "tags": [ "backfill" ] } ] }, "auto_submit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Submit", "description": "Submit the batch for processing immediately after creation \u2014 same behavior as the ?auto_submit query parameter (the query parameter wins when both are supplied). Default false: the batch is created in DRAFT status and must be submitted with POST /submit before the draft TTL expires or the reaper cancels it. Accepted in the body because callers kept passing it here and it was silently ignored \u2014 the batch parked DRAFT and vanished ~30min later with no signal (FRUSTRATIONS L751)." }, "trigger_processing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Trigger Processing", "description": "Deprecated alias of auto_submit (kept for callers taught by older docs/hints). auto_submit wins when both are supplied." } }, "type": "object", "title": "CreateBatchRequest", "description": "Request model for creating a new batch.\n\nBatches group bucket objects for processing into collections. When you submit a batch,\nall objects in the batch are processed through the collections associated with the bucket.\n\nProvide **either** ``object_ids`` (explicit list) **or** ``filters`` (server-side query) \u2014 not both.\n\n- object_ids: Explicit list of object IDs that exist in the bucket\n- filters: A LogicalOperator filter that is resolved server-side against the bucket's objects\n\nBatch Processing Flow:\n1. Create batch with object_ids or filters \u2192 Batch created in DRAFT status, collections auto-discovered\n2. Submit batch \u2192 Processing begins for discovered collections\n3. Collections with collection sources (tier 2/3) are processed automatically\n4. Processing happens in topological order based on collection dependencies\n\nExamples:\n Explicit object IDs:\n {\"object_ids\": [\"obj_123\", \"obj_456\", \"obj_789\"]}\n\n Filter-based (all objects with a tag):\n {\"filters\": {\"AND\": [{\"field\": \"metadata.batch_tag\", \"operator\": \"eq\", \"value\": \"nfl_2025\"}]}}" }, "CreateBenchmarkRequest": { "properties": { "benchmark_name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Benchmark Name", "description": "Human-readable name for this benchmark." }, "baseline_retriever_id": { "type": "string", "title": "Baseline Retriever Id", "description": "ID of the baseline retriever pipeline to compare against." }, "candidate_retriever_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Candidate Retriever Ids", "description": "IDs of candidate retriever pipelines to evaluate." }, "session_filter": { "anyOf": [ { "$ref": "#/components/schemas/SessionFilter-Input" }, { "type": "null" } ], "description": "Optional filter criteria for selecting sessions to replay." }, "session_count": { "type": "integer", "maximum": 10000.0, "minimum": 10.0, "title": "Session Count", "description": "Number of sessions to include in the benchmark.", "default": 1000 } }, "type": "object", "required": [ "benchmark_name", "baseline_retriever_id", "candidate_retriever_ids" ], "title": "CreateBenchmarkRequest", "description": "Request to create a new benchmark run." }, "CreateBlobRequest": { "properties": { "property": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Property", "description": "REQUIRED. Property name from the bucket schema that this blob belongs to. Must match a field defined in the bucket's schema. Used to validate blob type compatibility and determine storage path. Common values: 'video', 'thumbnail', 'transcript', 'document', 'image'", "examples": [ "video", "thumbnail", "transcript", "image", "document" ] }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Prefix", "description": "OPTIONAL. Storage path prefix for organizing blobs within the bucket. If not provided, uses default bucket organization. Use for: grouping blobs by campaign, date, category, etc. Example: 'campaigns/summer_2025' or 'products/electronics'", "examples": [ "campaigns/summer_2025", "products/electronics", "2025/Q4" ] }, "type": { "$ref": "#/components/schemas/BucketSchemaFieldType", "description": "REQUIRED. The schema field type for this blob. Must match the bucket schema definition for the property. Determines validation rules and processing pipeline. Common types: IMAGE, VIDEO, AUDIO, PDF, DOCUMENT, TEXT", "examples": [ "VIDEO", "IMAGE", "PDF", "AUDIO", "TEXT", "DOCUMENT" ] }, "data": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Data", "description": "EITHER data OR upload_id must be provided (mutually exclusive). \n\nFile data in one of several INTERCHANGEABLE formats: \n\n**Format 1: URL String (HTTP/HTTPS/S3)** - Direct URL to file on the web or in S3 - Examples: 'https://example.com/video.mp4', 's3://bucket/key' - Use for: Public files, existing S3 objects, pre-signed URLs - File is downloaded and uploaded to internal S3 (if canonicalize_source=True) \n\n**Format 2: Data URI String (base64)** - Self-contained base64 data with MIME type - Format: 'data:;base64,' - Example: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...' - Use for: Small files (<5MB), mobile uploads, inline test data - MIME type automatically extracted from URI - Data is decoded, validated, and uploaded to S3 automatically \n\n**Format 3: Base64 Dictionary** - Structured format with explicit metadata - Required keys: 'base64' (encoded data) - Optional keys: 'mime_type', 'filename' - Example: {'base64': '/9j/4AAQ...', 'mime_type': 'image/jpeg', 'filename': 'photo.jpg'} - Use for: When you need explicit MIME type control - Data is decoded, validated, and uploaded to S3 automatically \n\n**Format 4: URL Dictionary** - Structured format for URL references - Required keys: 'url' - Example: {'url': 'https://example.com/file.jpg'} - Use for: Consistency with other dict formats \n\n**Processing:** All formats are converted to internal S3 URLs before storage. The engine always receives S3 URLs regardless of input format. \n\n**Size Limits (Base64 only):** Base64 data: 5MB (free), 10MB (pro), 50MB (enterprise). URLs: No limit (downloaded on-demand). For files exceeding limits, use presigned upload workflow: POST /buckets/{id}/uploads \n\n**Validation:** - Base64: Encoding validated, MIME type detected, size checked - URLs: Accessibility verified, content-type validated - All: Schema type compatibility enforced", "examples": [ "https://example.com/video.mp4", "s3://my-bucket/path/to/image.jpg", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", { "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "mime_type": "image/png" }, { "base64": "/9j/4AAQSkZJRg...", "filename": "photo.jpg", "mime_type": "image/jpeg" }, { "url": "https://cdn.example.com/files/document.pdf" } ] }, "upload_id": { "anyOf": [ { "type": "string", "pattern": "^upl_[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Upload Id", "description": "EITHER upload_id OR data must be provided. Reference to an existing upload from the presigned URL workflow. \n\n\u26a0\ufe0f PRESIGNED URLS: Use existing POST /buckets/{id}/uploads endpoint! It already handles presigned URL generation, upload tracking, and validation. DO NOT create a new /presigned-upload endpoint - it's redundant. \n\nWorkflow: 1. POST /buckets/{id}/uploads \u2192 {upload_id, presigned_url} 2. User uploads file to presigned_url 3. POST /uploads/{upload_id}/confirm \u2192 Validates upload 4. Use upload_id here to reference the uploaded file \n\nThe upload must be in CONFIRMED or ACTIVE status. Format: 'upl_' prefix followed by alphanumeric characters. \n\nUse Cases: - Combine multiple uploads into one object - Upload files in parallel, create object later - Reuse same upload across multiple objects \n\nSee: api/buckets/uploads/ for the complete upload system", "examples": [ "upl_abc123def456", "upl_xyz789" ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Per-blob metadata. Promoted onto the object root at ingest so it reaches the processed document via field passthrough (BACKE-2540). Precedence: an explicit object-root field wins over a blob metadata key of the same name; across multiple blobs the first blob to set a key wins; system/reserved field names (object_id, collection_id, _internal, ...) are never overwritten. Put shared metadata at the object root directly; use blob metadata for per-blob attributes." }, "canonicalize_source": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Canonicalize Source", "description": "If set, override object-level default to control source canonicalization for this blob." }, "force_remirror": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Force Remirror", "description": "If set, override object-level default to force re-upload even if an identical blob exists." } }, "type": "object", "required": [ "property", "type" ], "title": "CreateBlobRequest", "description": "Request model for creating a new blob.\n\n\u26a0\ufe0f IMPORTANT: For presigned URL uploads, use the existing /buckets/{id}/uploads system!\n DO NOT create a new presigned upload endpoint - one already exists.\n\nSupports two modes:\n\nMode 1: Direct Data Upload\n - Provide 'data' field with URL or base64 content\n - File is processed immediately during object creation\n - Use for: Small files, public URLs, inline data\n\nMode 2: Upload Reference (Recommended for large files)\n - First: POST /buckets/{id}/uploads \u2192 Returns presigned_url + upload_id\n - User uploads file directly to S3 via presigned_url\n - Then: POST /uploads/{upload_id}/confirm \u2192 Validates upload\n - Finally: Reference upload_id in this blob request\n - Use for: Large files, client-side uploads, multi-blob objects\n\nWhy upload_id?\n - Combine multiple uploads into one object\n - Upload files in parallel, create object later\n - Reuse uploads across multiple objects\n - Better UX: upload progress, retry logic, validation\n\nRelated Endpoints:\n - POST /buckets/{id}/uploads - Generate presigned URLs (EXISTING SYSTEM)\n - POST /uploads/{id}/confirm - Confirm upload completed\n - See: api/buckets/uploads/services.py for full upload workflow\n\nExamples:\n # Direct data (simple)\n {\n \"property\": \"thumbnail\",\n \"type\": \"IMAGE\",\n \"data\": \"https://example.com/image.jpg\"\n }\n\n # Upload reference (recommended)\n {\n \"property\": \"video\",\n \"type\": \"VIDEO\",\n \"upload_id\": \"upl_abc123\" # From /uploads endpoint\n }\n\n # Multiple uploads \u2192 one object\n {\n \"blobs\": [\n {\"property\": \"video\", \"upload_id\": \"upl_video123\"},\n {\"property\": \"thumbnail\", \"upload_id\": \"upl_thumb456\"},\n {\"property\": \"transcript\", \"upload_id\": \"upl_trans789\"}\n ]\n }", "examples": [ { "data": "https://example.com/image.jpg", "description": "Direct data upload - Simple image from URL", "metadata": { "alt_text": "Product thumbnail" }, "property": "thumbnail", "type": "IMAGE" }, { "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAA//2Q==", "description": "Data URI upload - Mobile camera photo", "metadata": { "device": "iPhone 13", "location": "Store #42" }, "property": "photo", "type": "IMAGE" }, { "data": { "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "filename": "sales-chart-2025-11.png", "mime_type": "image/png" }, "description": "Base64 dict upload - Programmatically generated image", "metadata": { "chart_type": "line", "generated_at": "2025-11-08T10:30:00Z" }, "property": "chart", "type": "IMAGE" }, { "description": "Upload reference - Video from presigned upload", "metadata": { "duration_seconds": 120 }, "property": "video", "type": "VIDEO", "upload_id": "upl_abc123def456" }, { "canonicalize_source": false, "data": "s3://my-bucket/documents/contract-2025.pdf", "description": "S3 reference - Existing object", "metadata": { "department": "Legal", "year": 2025 }, "property": "archive", "type": "PDF" }, { "blobs": [ { "property": "video", "type": "VIDEO", "upload_id": "upl_video123" }, { "data": "data:image/png;base64,iVBORw0KG...", "property": "thumbnail", "type": "IMAGE" }, { "property": "transcript", "type": "TEXT", "upload_id": "upl_trans789" } ], "description": "Multiple uploads in one object - Complete media package", "note": "Use in array for multi-file objects" } ] }, "CreateBroadcastRequest": { "properties": { "body": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Body" }, "scope": { "anyOf": [ { "$ref": "#/components/schemas/SupportScope" }, { "type": "null" } ] }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" } }, "type": "object", "required": [ "body" ], "title": "CreateBroadcastRequest", "description": "Admin-only: a standalone communication not attached to a ticket." }, "CreateCheckoutRequest": { "properties": { "package": { "type": "string", "title": "Package", "description": "Credit package to purchase: starter, growth, or scale", "examples": [ "starter", "growth", "scale" ] }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url", "description": "Redirect URL after successful payment", "default": "https://studio.mixpeek.com/billing?checkout=success" }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url", "description": "Redirect URL if checkout is cancelled", "default": "https://studio.mixpeek.com/billing?checkout=cancelled" } }, "type": "object", "required": [ "package" ], "title": "CreateCheckoutRequest", "description": "Request to create a Stripe Checkout Session for credit purchase." }, "CreateCheckoutResponse": { "properties": { "checkout_url": { "type": "string", "title": "Checkout Url", "description": "Stripe-hosted checkout page URL", "examples": [ "https://checkout.stripe.com/c/pay/cs_live_abc123" ] }, "session_id": { "type": "string", "title": "Session Id", "description": "Stripe Checkout Session ID", "examples": [ "cs_live_abc123" ] } }, "type": "object", "required": [ "checkout_url", "session_id" ], "title": "CreateCheckoutResponse", "description": "Response with Stripe Checkout Session URL." }, "CreateClusterRequest": { "properties": { "collection_ids": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Collection Ids", "description": "Collections to cluster together" }, "cluster_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cluster Name", "description": "Optional human-friendly name for the clustering job" }, "cluster_type": { "$ref": "#/components/schemas/ClusterType", "description": "Vector or attribute clustering", "default": "vector" }, "vector_config": { "anyOf": [ { "$ref": "#/components/schemas/VectorBasedConfig-Input" }, { "type": "null" } ], "description": "Required when cluster_type is 'vector'" }, "attribute_config": { "anyOf": [ { "$ref": "#/components/schemas/AttributeBasedConfig" }, { "type": "null" } ], "description": "Required when cluster_type is 'attribute'" }, "filters": { "anyOf": [ { "$ref": "#/components/schemas/LogicalOperator-Input" }, { "type": "null" } ], "description": "Optional filters to pre-filter documents before clustering (same format as list documents). Applied during Qdrant scroll before parquet export. Useful for clustering subsets like: status='active', category='electronics', etc." }, "llm_labeling": { "anyOf": [ { "$ref": "#/components/schemas/LLMLabeling-Input" }, { "type": "null" } ], "description": "Optional configuration for LLM-based cluster labeling. When provided with enabled=True, clusters will have semantic labels generated by LLM instead of generic labels like 'Cluster 0'. When not provided or enabled=False, uses fallback labels." }, "enrich_source_collection": { "type": "boolean", "title": "Enrich Source Collection", "description": "If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern.", "default": false }, "source_enrichment_config": { "anyOf": [ { "$ref": "#/components/schemas/SourceEnrichmentConfig" }, { "type": "null" } ], "description": "Configuration for source collection enrichment (only used if enrich_source_collection=True). Controls which fields are added to source documents and field naming conventions." }, "auto_execute_on_batch": { "type": "boolean", "title": "Auto Execute On Batch", "description": "Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API.", "default": false }, "auto_execute_min_documents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Auto Execute Min Documents", "description": "Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped." }, "auto_execute_cooldown_seconds": { "type": "integer", "title": "Auto Execute Cooldown Seconds", "description": "Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).", "default": 3600 } }, "type": "object", "required": [ "collection_ids" ], "title": "CreateClusterRequest", "description": "Create a clustering job for one or more collections.", "examples": [ { "cluster_name": "products_clip_hdbscan", "cluster_type": "vector", "collection_ids": [ "col_products_v1", "col_products_v2" ], "llm_labeling": { "enabled": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "description", "source_type": "payload" } ] }, "model_name": "gpt-4o-mini-2024-07-18", "provider": "openai" }, "vector_config": { "clustering_method": "hdbscan", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "hdbscan_parameters": { "min_cluster_size": 10, "min_samples": 5 }, "sample_size": 5000 } }, { "cluster_name": "video_multimodal_clustering", "cluster_type": "vector", "collection_ids": [ "col_videos_v1" ], "llm_labeling": { "enabled": true, "include_keywords": true, "include_summary": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "title", "source_type": "payload" }, { "input_key": "video_url", "path": "video_url", "source_type": "payload" } ] }, "model_name": "gemini-2.5-flash-lite", "provider": "google" }, "vector_config": { "clustering_method": "hdbscan", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "hdbscan_parameters": { "min_cluster_size": 5, "min_samples": 3 }, "sample_size": 3000 } }, { "cluster_name": "image_multimodal_clustering", "cluster_type": "vector", "collection_ids": [ "col_images_v1" ], "llm_labeling": { "enabled": true, "labeling_inputs": { "input_mappings": [ { "input_key": "text", "path": "caption", "source_type": "payload" }, { "input_key": "image_url", "path": "image_url", "source_type": "payload" } ] }, "model_name": "gemini-2.5-flash-lite", "provider": "google" }, "vector_config": { "clustering_method": "kmeans", "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding", "kmeans_parameters": { "n_clusters": 10 }, "sample_size": 2000 } }, { "attribute_config": { "attributes": [ "status" ], "hierarchical_grouping": true }, "cluster_name": "orders_group_by_status", "cluster_type": "attribute", "collection_ids": [ "col_orders_v1", "col_orders_v2", "col_orders_v3" ] } ] }, "CreateCollectionRequest": { "properties": { "collection_name": { "type": "string", "title": "Collection Name", "description": "Name of the collection to create", "examples": [ "video_frames", "product_embeddings" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the collection" }, "source": { "$ref": "#/components/schemas/SourceConfig-Input", "description": "Source configuration (bucket or collection) for this collection" }, "input_schema": { "anyOf": [ { "$ref": "#/components/schemas/BucketSchema-Input" }, { "type": "null" } ], "description": "Input schema for the collection. If not provided, inferred from source bucket's bucket_schema or source collection's output_schema. REQUIRED for input_mappings to work - defines what fields can be mapped to feature extractors." }, "feature_extractor": { "$ref": "#/components/schemas/shared__collection__features__extractors__models__FeatureExtractorConfig-Input", "description": "Single feature extractor for this collection. Use field_passthrough within the extractor config to include additional source fields. For multiple extractors, create multiple collections and use collection-to-collection pipelines. DEPRECATED for direct use: prefer `features: [...]` (contract v2 \u00a76.2, D9) \u2014 extractor names are internal implementation." }, "features": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Features", "description": "What you want to search by: feature keys from GET /v1/collections/features (e.g. ['faces'] or ['custom:']). Resolved to the processing pipeline server-side \u2014 the preferred alternative to `feature_extractor`. Provide one or the other." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the collection is enabled", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata for the collection" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/CollectionScheduleConfig" }, { "type": "null" } ], "description": "Optional schedule for automatic re-processing. Creates a COLLECTION_TRIGGER trigger behind the scenes. Supports cron and interval schedules." }, "taxonomy_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaxonomyApplicationConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Taxonomy Applications", "description": "Optional taxonomy applications to automatically enrich documents in this collection. Each taxonomy will classify/enrich documents based on configured retriever matches." }, "cluster_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ClusterApplicationConfig" }, "type": "array" }, { "type": "null" } ], "title": "Cluster Applications", "description": "Optional cluster applications to automatically execute when batch processing completes. Each cluster enriches documents with cluster assignments (cluster_id, cluster_label, etc.)." }, "alert_applications": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AlertApplicationConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Alert Applications", "description": "Optional alert applications to automatically execute when documents are ingested. Each alert runs a retriever against new documents and sends notifications if matches are found. Supports both ON_INGEST (triggered per batch) and SCHEDULED (periodic) execution modes." }, "retriever_enrichments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RetrieverEnrichmentConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Retriever Enrichments", "description": "Optional retriever enrichments to run on documents during post-processing. Each enrichment executes a retriever pipeline and writes selected result fields back to the document. Use for: LLM classification, cross-collection joins, multi-stage enrichment at ingestion time." }, "embedding_task": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embedding Task", "description": "Override the embedding task hint for instruction-aware models (E5, Gemini). Defaults to 'retrieval_document' for indexing pipelines. Values: retrieval_document, retrieval_query, semantic_similarity, classification, clustering. Only change this if your primary use case is not retrieval (e.g., clustering or classification). Applied to all task-aware embedding models in this collection's extractor pipeline." } }, "type": "object", "required": [ "collection_name", "source", "feature_extractor" ], "title": "CreateCollectionRequest", "description": "Request model for creating a new collection.\n\nCollections process data from buckets or other collections using a single feature extractor.\n\nKEY ARCHITECTURAL CHANGE: Each collection has EXACTLY ONE feature extractor.\n- Use field_passthrough to include additional source fields in output documents\n- Multiple extractors = multiple collections\n- This simplifies processing and makes output schema deterministic\n\nCRITICAL: To use input_mappings:\n1. Your source bucket MUST have a bucket_schema defined\n2. The input_mappings reference fields from that bucket_schema\n3. The system validates that mapped fields exist in the source schema\n\nExample workflow:\n1. Create bucket with schema: { \"properties\": { \"image\": {\"type\": \"image\"}, \"title\": {\"type\": \"string\"} } }\n2. Upload objects conforming to that schema\n3. Create collection with:\n - input_mappings: { \"image\": \"image\" }\n - field_passthrough: [{\"source_path\": \"title\"}]\n4. Output documents will have both extractor outputs AND passthrough fields\n\nSchema Computation:\n- output_schema is computed IMMEDIATELY when collection is created\n- output_schema = field_passthrough fields + extractor output fields\n- No waiting for documents to be processed!", "examples": [ { "collection_name": "product_embeddings", "description": "Generate image embeddings with passthrough fields", "enabled": true, "feature_extractor": { "feature_extractor_name": "image_extractor", "field_passthrough": [ { "required": true, "source_path": "title" }, { "source_path": "category" } ], "input_mappings": { "image": "product_image" }, "parameters": { "model": "clip-vit-base-patch32" }, "version": "v1" }, "source": { "bucket_ids": [ "bkt_products" ], "type": "bucket" } }, { "collection_name": "video_frames", "description": "Extract frames from videos with metadata passthrough", "feature_extractor": { "feature_extractor_name": "multimodal_extractor", "field_passthrough": [ { "source_path": "campaign_id" }, { "source_path": "duration_seconds" } ], "input_mappings": { "video": "video_url" }, "parameters": { "fps": 1 }, "version": "v1" }, "source": { "bucket_ids": [ "bkt_videos" ], "type": "bucket" } }, { "collection_name": "scenes_from_frames", "description": "Detect scenes from frame collection (collection-to-collection)", "feature_extractor": { "feature_extractor_name": "scene_detector", "field_passthrough": [ { "source_path": "campaign_id" } ], "input_mappings": { "image": "frame_url" }, "version": "v1" }, "source": { "collection_id": "col_video_frames", "type": "collection" } } ] }, "CreateDatasetRequest": { "properties": { "dataset_name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Dataset Name", "description": "Unique name for this dataset" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of what this dataset measures" }, "queries": { "items": { "$ref": "#/components/schemas/GroundTruthQuery" }, "type": "array", "minItems": 1, "title": "Queries", "description": "List of queries with ground truth relevance labels" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata" } }, "type": "object", "required": [ "dataset_name", "queries" ], "title": "CreateDatasetRequest", "description": "Request model for creating a new evaluation dataset." }, "CreateMessageRequest": { "properties": { "body": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Body" }, "author_type": { "anyOf": [ { "$ref": "#/components/schemas/SupportAuthorType" }, { "type": "null" } ] }, "attachments": { "items": { "$ref": "#/components/schemas/SupportAttachment" }, "type": "array", "title": "Attachments" } }, "type": "object", "required": [ "body" ], "title": "CreateMessageRequest" }, "CreateMigrationRequest": { "properties": { "config": { "$ref": "#/components/schemas/MigrationConfig", "description": "Migration configuration" }, "start_immediately": { "type": "boolean", "title": "Start Immediately", "description": "Start execution immediately after validation", "default": false } }, "type": "object", "required": [ "config" ], "title": "CreateMigrationRequest", "description": "Request to create a new migration.", "example": { "config": { "feature_extractors": [ { "feature_extractor_name": "openai_text_embedding", "parameters": { "model": "text-embedding-3-large" }, "version": "v3" } ], "migration_type": "re_extract", "source_namespace_id": "ns_abc123", "target_namespace_name": "my_namespace_v2" }, "start_immediately": false } }, "CreateMigrationResponse": { "properties": { "migration_id": { "type": "string", "title": "Migration Id", "description": "Created migration ID" }, "status": { "$ref": "#/components/schemas/MigrationStatus", "description": "Current status" }, "validation_result": { "anyOf": [ { "$ref": "#/components/schemas/ValidationResult" }, { "type": "null" } ], "description": "Validation result if available" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp" }, "message": { "type": "string", "title": "Message", "description": "Human-readable message" } }, "type": "object", "required": [ "migration_id", "status", "created_at", "message" ], "title": "CreateMigrationResponse", "description": "Response after creating a migration.", "example": { "created_at": "2025-12-03T10:00:00Z", "message": "Migration created successfully. Use POST /migrations/{id}/start to begin execution.", "migration_id": "mig_abc123xyz789", "status": "draft", "validation_result": { "errors": [], "estimated_duration_seconds": 1800, "estimated_resources": { "cluster": 1, "collection": 5, "taxonomy": 2 }, "valid": true, "warnings": [] } } }, "CreateModelUploadRequest": { "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{2,63}$", "title": "Name", "description": "Model name: 3-64 chars, letters/numbers/underscores, starts with a letter (no hyphens or spaces)", "examples": [ "custom_embedder", "sentiment_model", "image_classifier" ] }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "title": "Version", "description": "Semantic version string", "examples": [ "1.0.0", "2.1.3", "0.0.1" ] }, "model_format": { "type": "string", "enum": [ "safetensors", "onnx", "pytorch", "huggingface" ], "title": "Model Format", "description": "Format of the model weights", "examples": [ "safetensors", "onnx", "pytorch", "huggingface" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description", "description": "Optional description of the model" }, "file_size_bytes": { "anyOf": [ { "type": "integer", "maximum": 5368709120.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "File Size Bytes", "description": "Expected file size in bytes for quota validation" }, "presigned_url_expiration": { "type": "integer", "maximum": 86400.0, "minimum": 60.0, "title": "Presigned Url Expiration", "description": "Presigned URL expiration time in seconds (1-24 hours)", "default": 3600 }, "resource_requirements": { "$ref": "#/components/schemas/ModelResourceRequirements", "description": "Resource requirements for model deployment" }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "description": "ML framework (e.g., sentence-transformers, transformers)" }, "task_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Type", "description": "Task type (e.g., embedding, classification, generation)" }, "source": { "type": "string", "enum": [ "customer", "mixpeek", "system" ], "title": "Source", "description": "Who is uploading: 'customer' (default) or 'mixpeek' (professional services). Mixpeek-sourced models are non-exportable by default.", "default": "customer" } }, "type": "object", "required": [ "name", "version", "model_format" ], "title": "CreateModelUploadRequest", "description": "Request to generate a presigned URL for model archive upload.\n\nThis is step 1 of the presigned URL workflow:\n1. POST /models/uploads \u2192 Returns presigned_url + upload_id\n2. PUT presigned_url with model archive (client uploads directly to S3)\n3. POST /models/uploads/{upload_id}/confirm \u2192 Validates and creates model\n\nRequirements:\n - name: Model name (e.g., 'my_custom_embedder')\n - version: Semantic version (e.g., '1.0.0')\n - model_format: Format of the model weights\n - file_size_bytes: Expected archive size for quota validation" }, "CreateNamespaceRequest": { "properties": { "namespace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namespace Id", "description": "Optional namespace ID override. Used for recovery/migration when recreating a namespace with a known ID. If not provided, a new ID is auto-generated." }, "namespace_name": { "type": "string", "maxLength": 64, "minLength": 3, "title": "Namespace Name", "description": "Name of the namespace to create", "example": "product-search" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode", "description": "Namespace mode. 'managed' (default) uses Mixpeek feature extractors. 'standalone' allows BYO vectors without extractors. If omitted and ONLY `vector_configs` is provided (no `features`/`feature_extractors`), standalone is inferred.", "default": "managed" }, "namespace_type": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceType" }, { "type": "null" } ], "description": "Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets.", "default": "standard" }, "scope": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceScope" }, { "type": "null" } ], "description": "Ownership scope. ORG (default) creates an org-scoped namespace. SYSTEM requires Mixpeek admin privileges and creates a namespace visible read-only to every org \u2014 used for curated sample corpora.", "default": "org" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the namespace", "example": "This namespace contains playlists from Spotify" }, "features": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Features", "description": "Modality+features config (contract v2 \u00a76.2, D9): feature keys from GET /v1/collections/features (e.g. ['image_search', 'faces'] or ['custom:']). Resolved server-side to the UNION of feature extractors the namespace needs \u2014 the preferred alternative to `feature_extractors` (extractor names are internal implementation). A namespace hosts many collections, so multiple features spanning multiple extractors are fine here. May be combined with `feature_extractors` (the two merge as a union). If neither is provided, the namespace gets the standard baseline (same as the scaffolded default namespace). Managed mode only.", "examples": [ [ "image_search", "text_search", "faces" ] ] }, "feature_extractors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BaseFeatureExtractorModel-Input" }, "type": "array" }, { "type": "null" } ], "title": "Feature Extractors", "description": "List of feature extractors to configure for this namespace. DEPRECATED for direct use: prefer `features: [...]` (contract v2 \u00a76.2, D9) \u2014 extractor names are internal implementation. Not used for standalone mode. If neither `features` nor `feature_extractors` is provided, the namespace defaults to the standard baseline. Each extractor requires 'feature_extractor_name' and 'version'. Optional 'params' can be specified for extractors with configurable settings (e.g., model selection) that affect vector dimensions. These params are locked at namespace creation time. Example: [{\"feature_extractor_name\": \"multimodal_extractor\", \"version\": \"v1\"}]", "examples": [ [ { "feature_extractor_name": "multimodal_extractor", "version": "v1" }, { "feature_extractor_name": "image_extractor", "params": { "model": "siglip_base" }, "version": "v1" } ] ] }, "vector_configs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/VectorConfigSpec" }, "type": "array" }, { "type": "null" } ], "title": "Vector Configs", "description": "Optional vector index configurations for standalone mode. Each entry defines a named vector index with dimension and distance metric. If omitted, indexes are auto-created on first upsert (schema-on-write).", "examples": [ [ { "dimension": 768, "metric": "cosine", "name": "clip" } ] ] }, "payload_indexes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PayloadIndexConfig-Input" }, "type": "array" }, { "type": "null" } ], "title": "Payload Indexes", "description": "Optional list of custom payload index configurations. Indexes required by selected feature extractors will be added automatically.", "example": [ { "field_name": "metadata.title", "field_schema": { "lowercase": true, "max_token_len": 15, "min_token_len": 2, "tokenizer": "word", "type": "text" }, "is_protected": false, "type": "text" }, { "field_name": "metadata.description", "field_schema": { "is_tenant": true, "type": "keyword" }, "is_protected": false, "type": "keyword" } ] }, "auto_create_indexes": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Create Indexes", "description": "Enable automatic creation of Qdrant payload indexes based on filter usage patterns. When enabled, the system tracks which fields are most frequently filtered (>100 queries/24h) and automatically creates indexes to improve query performance. Background task runs every 6 hours. Expected performance improvement: 50-90% latency reduction for filtered queries. Defaults: managed namespaces off, standalone namespaces on. Set explicitly to false to opt out (including for standalone, so an agent can manage indexes itself).", "example": true }, "ttl_seconds": { "anyOf": [ { "type": "integer", "minimum": 60.0 }, { "type": "null" } ], "title": "Ttl Seconds", "description": "Time-to-live in seconds. Namespace will be auto-deleted after this duration." }, "infrastructure": { "anyOf": [ { "$ref": "#/components/schemas/NamespaceInfrastructure-Input" }, { "type": "null" } ], "description": "Optional dedicated infrastructure configuration for this namespace. Required for custom plugins and custom models (Enterprise tier). If None, uses shared infrastructure or organization-level infrastructure." } }, "type": "object", "required": [ "namespace_name" ], "title": "CreateNamespaceRequest", "description": "Request schema for creating a new namespace.", "examples": [ { "features": [ "image_search", "text_search", "faces" ], "namespace_name": "media_library" }, { "feature_extractors": [ { "feature_extractor_name": "multimodal_extractor", "version": "v1" } ], "namespace_name": "product_catalog" }, { "description": "Video content with text and image embeddings", "feature_extractors": [ { "feature_extractor_name": "text_extractor", "version": "v1" }, { "feature_extractor_name": "image_extractor", "version": "v1" } ], "namespace_name": "video_library", "payload_indexes": [ { "field_name": "metadata.title", "type": "text" } ] } ] }, "CreateNodeFromDocumentsRequest": { "properties": { "node_label": { "type": "string", "minLength": 1, "title": "Node Label", "description": "Label for the new node \u2014 the value copied onto documents that classify under it (canonical `label` field)." }, "documents": { "items": { "$ref": "#/components/schemas/DocumentRef" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Documents", "description": "Documents whose stored vectors define the node's anchor (centroid). 1-200 refs; for large selections send a sample \u2014 the centroid converges quickly." }, "node_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Node Fields", "description": "Optional extra fields stored on the node document (e.g. `description`). Only fields listed in the taxonomy's enrichment_fields are copied during enrichment." }, "vector_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vector Name", "description": "Optional explicit vector (index) name for the anchor. If omitted, it is derived from the taxonomy's node collection vector indexes." }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Optional freeform origin context (e.g. cluster_id, run_id, selection type). Stored on the node document under `metadata.promotion` for auditability." } }, "type": "object", "required": [ "node_label", "documents" ], "title": "CreateNodeFromDocumentsRequest", "description": "Create a taxonomy node whose classification anchor derives from documents.\n\nMixpeek taxonomy nodes are documents in the taxonomy's source (node)\ncollection: at enrichment time, an incoming document's embedding queries\nthat collection through the taxonomy's retriever and the best-matching\nnode's fields (canonically `label`) are copied onto it.\n\nThis endpoint computes the CENTROID of the referenced documents' stored\nvectors and inserts it as a new node document \u2014 so future documents whose\nembeddings land near the referenced selection are classified under\n`node_label`. No re-embedding or GPU work happens; only stored vectors are\nread." }, "CreateObjectRequest": { "properties": { "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Prefix", "description": "Storage key/path prefix of the object, this will be used to retrieve the object from the storage. It's at the root of the object.", "example": "/contract-2024" }, "blobs": { "items": { "$ref": "#/components/schemas/CreateBlobRequest" }, "type": "array", "title": "Blobs", "description": "List of blobs to be created in this object", "example": [ { "data": { "num_pages": 5, "title": "Service Agreement 2024" }, "key_prefix": "/content.pdf", "metadata": { "author": "John Doe", "department": "Legal" }, "property": "content", "type": "PDF" } ] }, "edges": { "items": { "$ref": "#/components/schemas/EdgeModel" }, "type": "array", "title": "Edges", "description": "Typed, directed relationships from this object to other objects (customer-owned, root-level \u2014 never `_internal`). Populated by source adapters from companion/sidecar files, or directly on upsert. Flows to the document + MVS payload so the `traverse_edge` retriever stage can follow it." }, "idempotency_key": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Idempotency Key", "description": "Client-generated idempotency key for safe retries. If an object with the same idempotency_key already exists in this bucket, the existing object is returned instead of creating a duplicate. Use a UUID or deterministic hash per object." }, "skip_duplicates": { "type": "boolean", "title": "Skip Duplicates", "description": "Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped.", "default": false }, "canonicalize_source": { "type": "boolean", "title": "Canonicalize Source", "description": "Mirror non-S3 sources into internal S3 and reference canonically.", "default": true }, "force_remirror": { "type": "boolean", "title": "Force Remirror", "description": "Force re-upload to S3 even if a blob with identical content already exists.", "default": false } }, "additionalProperties": true, "type": "object", "title": "CreateObjectRequest", "description": "Request model for creating a bucket object.\n\nObjects can be created with blobs from two sources:\n1. Direct data (URLs, base64) - Use CreateBlobRequest.data field\n2. Upload references - Use CreateBlobRequest.upload_id field (from POST /buckets/{id}/uploads)\n\nUpload Reference Workflow:\n For large files or client-side uploads, use the presigned URL workflow:\n 1. POST /buckets/{id}/uploads \u2192 Returns {upload_id, presigned_url}\n 2. User uploads file to presigned_url (client-side)\n 3. POST /uploads/{upload_id}/confirm \u2192 Validates upload\n 4. POST /buckets/{id}/objects with upload_id in blobs (this endpoint)\n\nUse Cases:\n - Single blob with direct data (simple)\n - Multiple blobs from presigned uploads (recommended for large files)\n - Mix of direct data and upload references\n - Combine multiple uploads into one object\n\nSee Also:\n - CreateBlobRequest for blob field documentation\n - POST /buckets/{id}/uploads for presigned URL generation", "example": { "blobs": [ { "data": { "num_pages": 5, "title": "Service Agreement 2024" }, "key_prefix": "/contract-2024/content.pdf", "metadata": { "author": "John Doe", "department": "Legal" }, "property": "content", "type": "json" }, { "data": { "filename": "https://example.com/images/smartphone-x1.jpg", "mime_type": "image/jpeg" }, "key_prefix": "/contract-2024/thumbnail.jpg", "metadata": { "height": 300, "width": 200 }, "property": "thumbnail", "type": "image" } ], "key_prefix": "/documents", "metadata": { "category": "contracts", "status": "draft", "year": 2024 } } }, "CreateObjectsBatchRequest": { "properties": { "objects": { "items": { "$ref": "#/components/schemas/CreateObjectRequest" }, "type": "array", "maxItems": 100, "title": "Objects", "description": "List of objects to be created in this batch (max 100)." } }, "type": "object", "required": [ "objects" ], "title": "CreateObjectsBatchRequest", "description": "Request model for creating multiple bucket objects in a batch.", "examples": [ { "objects": [ { "blobs": [ { "data": { "num_pages": 5, "title": "Service Agreement 2024" }, "key_prefix": "/contract-2024/content.pdf", "metadata": { "author": "John Doe", "department": "Legal" }, "property": "content", "type": "json" } ], "key_prefix": "/documents", "metadata": { "category": "contracts", "status": "draft", "year": 2024 } } ] } ] }, "CreateObjectsBatchResponse": { "properties": { "succeeded": { "items": { "$ref": "#/components/schemas/ObjectResponse" }, "type": "array", "title": "Succeeded", "description": "List of successfully created objects" }, "failed": { "items": { "$ref": "#/components/schemas/FailedObjectError" }, "type": "array", "title": "Failed", "description": "List of objects that failed to create with error details" }, "total_requested": { "type": "integer", "title": "Total Requested", "description": "Total number of objects in the batch request" }, "succeeded_count": { "type": "integer", "title": "Succeeded Count", "description": "Number of objects successfully created" }, "failed_count": { "type": "integer", "title": "Failed Count", "description": "Number of objects that failed" } }, "type": "object", "required": [ "succeeded", "failed", "total_requested", "succeeded_count", "failed_count" ], "title": "CreateObjectsBatchResponse", "description": "Response model for batch object creation with partial success support.\n\nThis endpoint uses partial success: valid objects are created even if some fail.\nFailed objects are tracked separately so users can fix and retry them.", "examples": [ { "failed": [ { "error": "Schema validation failed: Missing required field 'title'", "error_type": "ValidationError", "object_index": 15 } ], "failed_count": 1, "succeeded": [ { "bucket_id": "bkt_9xy8z7", "object_id": "obj_123abc", "status": "DRAFT" } ], "succeeded_count": 99, "total_requested": 100 } ] }, "CreateRetrieverAPIKeyRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Human-friendly key label for identification." }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description", "description": "Optional description explaining the key's purpose." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional UTC timestamp when the key automatically expires." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins", "description": "Optional list of allowed HTTP origins for this API key. When set, browser requests must include a matching Origin header. Supports exact matches and wildcard subdomains (e.g., 'https://*.example.com'). Defense-in-depth: Origin headers can be spoofed from non-browser contexts.", "examples": [ [ "https://docs.example.com", "https://*.example.com" ] ] } }, "type": "object", "required": [ "name" ], "title": "CreateRetrieverAPIKeyRequest", "description": "Request payload for creating a retriever-scoped API key.\n\nRetriever keys are automatically scoped to execute a specific retriever.\nThe scope and permissions are auto-populated by the service layer and cannot be modified.\n\nExample:\n {\n \"name\": \"production-api\",\n \"description\": \"Production API key for customer integrations\",\n \"expires_at\": \"2026-12-31T23:59:59Z\"\n }", "examples": [ { "description": "Production API key for external service", "expires_at": "2026-12-31T23:59:59Z", "name": "production-key" } ] }, "CreateRetrieverRequest": { "properties": { "retriever_name": { "type": "string", "minLength": 1, "title": "Retriever Name", "description": "Unique retriever name (REQUIRED)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human readable retriever description (OPTIONAL)." }, "visibility": { "$ref": "#/components/schemas/RetrieverVisibility", "description": "Visibility level: PRIVATE (owner only), PUBLIC (any valid API key), MARKETPLACE (requires subscription). Defaults to PRIVATE.", "default": "private" }, "marketplace_listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Marketplace Listing Id", "description": "Associated marketplace listing ID when visibility is MARKETPLACE (OPTIONAL)." }, "requires_subscription": { "type": "boolean", "title": "Requires Subscription", "description": "Whether this retriever requires an active subscription to access (marketplace only).", "default": false }, "collection_identifiers": { "items": { "type": "string" }, "type": "array", "title": "Collection Identifiers", "description": "Collection identifiers (names or IDs) queried by the retriever (OPTIONAL). Identifiers can be collection names (e.g., 'my_collection') or collection IDs (e.g., 'col_abc123'). The system will resolve names to IDs automatically. Can be empty for inference-only pipelines (e.g., LLM query analysis without document retrieval). Also accepts 'collection_ids' as an alias for backward compatibility.", "examples": [ [ "my_collection", "products" ], [ "col_abc123", "col_def456" ], [] ] }, "stages": { "items": { "$ref": "#/components/schemas/StageConfig-Input" }, "type": "array", "minItems": 1, "title": "Stages", "description": "Ordered stage configurations (REQUIRED). Each stage is {\"stage_name\":