{"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.81"},"servers":[{"url":"https://api.mixpeek.com","description":"Production"}],"paths":{"/v1/private/organizations":{"post":{"tags":["Private"],"summary":"Create Organization Private","description":"Create a new private organization.\n\nNOTE: This endpoint returns OrganizationModel (with internal_id) instead of\nOrganizationModelResponse because it's admin-only and callers need the\ninternal_id for service initialization and E2E testing.","operationId":"create_organization_private_v1_private_organizations_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationModel"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/private/organizations/{organization_identifier}":{"get":{"tags":["Private"],"summary":"Get Organization Private","description":"Get a private organization by ID or name.","operationId":"get_organization_private_v1_private_organizations__organization_identifier__get","parameters":[{"name":"organization_identifier","in":"path","required":true,"schema":{"type":"string","title":"Organization Identifier"}}],"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"}}}}}},"patch":{"tags":["Private"],"summary":"Update Organization Private","description":"Admin-only: update organization tier, rate limits, and infrastructure.\n\nSecurity: This endpoint is ONLY accessible with MIXPEEK_PRIVATE_TOKEN.\nIt allows updating infrastructure configuration (Qdrant/Ray URLs) for ENTERPRISE customers.\n\nInfrastructure updates require Mixpeek admin privileges and are logged for audit.","operationId":"update_organization_private_v1_private_organizations__organization_identifier__patch","parameters":[{"name":"organization_identifier","in":"path","required":true,"schema":{"type":"string","title":"Organization Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationAdminUpdateRequest"}}}},"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"}}}}}},"delete":{"tags":["Private"],"summary":"Delete Organization Private","description":"Delete a private organization.","operationId":"delete_organization_private_v1_private_organizations__organization_identifier__delete","parameters":[{"name":"organization_identifier","in":"path","required":true,"schema":{"type":"string","title":"Organization Identifier"}}],"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"}}}}}}},"/v1/private/organizations/add-user":{"post":{"tags":["Private"],"summary":"Add User To Organization Private","description":"Add a user to a private organization.","operationId":"add_user_to_organization_private_v1_private_organizations_add_user_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddUserToOrganizationRequest"}}},"required":true},"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"}}}}}}},"/v1/private/organizations/remove-user":{"post":{"tags":["Private"],"summary":"Remove User From Organization Private","description":"Remove a user from an organization by email (admin-only).\n\nMirrors the add-user endpoint. Accepts:\n - organization_identifier: org ID or name\n - email: user email to remove","operationId":"remove_user_from_organization_private_v1_private_organizations_remove_user_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"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"}}}}}}},"/v1/private/organizations/{organization_id}/users/{user_email}/bootstrap-key":{"post":{"tags":["Private"],"summary":"Create Bootstrap Api Key","description":"Create the organization's primary API key (requires MIXPEEK_PRIVATE_KEY).\n\nšŸ”‘ IMPORTANT - Two Different Keys (DO NOT CONFUSE):\n\n1. MIXPEEK_PRIVATE_KEY (what you use to call THIS endpoint):\n - Static, hardcoded token shared between studio proxy and backend\n - Used ONLY for server-to-server /v1/private/* endpoint calls\n - Never changes, never stored in database\n - Never used by frontend UI\n - Example: xnefritAiaKQiddNL3ZHWEN4cHWLsCkwEycUDLU2wLekQEuf\n\n2. Organization API Key (what THIS endpoint creates and returns):\n - Created ONCE per organization with ADMIN permissions\n - Used by frontend UI for ALL /v1/* API calls\n - Named \"admin-key\" and stored in database (hashed)\n - Plaintext returned ONCE on creation\n - šŸ”’ PROTECTED: Users CANNOT delete, rotate, or change permissions on this key\n - Example: sk_kbHvXHAySDUrzrPo2ajwmqBAXJ...\n\nThis endpoint creates an Organization API key (type #2) that the frontend will use.\nIt does NOT create, modify, or touch the MIXPEEK_PRIVATE_KEY (type #1).\n\nāš ļø The plaintext key is only returned ONCE on creation - store it in localStorage!\nāœ… If called when key exists: Revokes old key and returns a new one (idempotent)","operationId":"create_bootstrap_api_key_v1_private_organizations__organization_id__users__user_email__bootstrap_key_post","parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string","title":"Organization Id"}},{"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 Create Bootstrap Api Key V1 Private Organizations Organization Id Users User Email Bootstrap Key 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"}}}}}}},"/v1/private/organizations/invitations/{email}":{"get":{"tags":["Private"],"summary":"Get Pending Invitations","description":"Return all pending Mixpeek invitations for the given email address.\n\nSearches across all organizations for users with this email and status=pending.\nUsed on the signup flow to offer invited users a chance to join their org.","operationId":"get_pending_invitations_v1_private_organizations_invitations__email__get","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Pending Invitations V1 Private Organizations Invitations 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"}}}}}}},"/v1/private/organizations/invitations/accept":{"post":{"tags":["Private"],"summary":"Accept Invitation","description":"Activate a pending invitation (status: pending ā†’ active).\n\nExpected payload:\n email: str\n organization_id: str\n user_name: str | None (optional, updates display name)","operationId":"accept_invitation_v1_private_organizations_invitations_accept_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Accept Invitation V1 Private Organizations Invitations Accept 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"}}}}}}},"/v1/private/configurations/storage/cors":{"get":{"tags":["Private"],"summary":"Get Current CORS Configuration","description":"Retrieve the current CORS configuration for the object storage bucket.\n\n **Use this to:**\n - Verify CORS is properly configured\n - Check which origins are currently allowed\n - Troubleshoot CORS-related issues\n - Audit current security settings","operationId":"get_storage_cors_v1_private_configurations_storage_cors_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CORSConfigurationInfo"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Private"],"summary":"Configure CORS for Object Storage","description":"Configure CORS (Cross-Origin Resource Sharing) on the object storage bucket.\n\n **Why is this needed?**\n When using presigned URLs for browser-based uploads, browsers enforce CORS policies.\n Without proper CORS configuration, uploads from the frontend will fail with CORS errors.\n\n **When to use this:**\n - During initial setup of the Mixpeek platform\n - When adding new frontend domains (development, staging, production)\n - When troubleshooting browser upload failures\n\n **Important notes:**\n - This is an admin-only operation (requires admin API key)\n - CORS is configured on the entire object storage bucket (not per-namespace)\n - Changes take effect immediately but may be cached by browsers\n - This works for any object storage provider (S3, LocalStack, GCS)\n\n **Common use cases:**\n 1. Local development: Configure localhost origins\n 2. Production: Configure production domain origins\n 3. Multi-environment: Configure multiple origins for dev/staging/prod","operationId":"configure_storage_cors_v1_private_configurations_storage_cors_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureCORSRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CORSConfigurationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/private/configurations/clickhouse/diagnostics":{"get":{"tags":["Private"],"summary":"Diagnose ClickHouse Configuration","description":"Run diagnostics on ClickHouse to check version, settings, and data type behavior.\n\n This is useful for:\n - Debugging differences between local and production environments\n - Verifying ClickHouse configuration\n - Checking if COUNT() returns strings or integers","operationId":"diagnose_clickhouse_v1_private_configurations_clickhouse_diagnostics_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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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āš ļø **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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/v1/public/pages/{slug}":{"get":{"tags":["Public Pages API"],"summary":"Get public Page config","description":"Fetch the full configuration for a public Page ā€” no authentication required.\n\nUsed by the `mxp.co/p/{slug}` frontend to render the page. Returns tabs,\nhero, stats, sections, theme, and SEO settings. Password-protected pages\nreturn a `password_protected: true` flag and omit sensitive config until\nthe password is verified at the search endpoint.\n\nThis endpoint is called automatically by `mxp.co/p/{slug}` on page load.\nYou only need to call it directly if you are building a custom frontend.","operationId":"get_public_page_config_v1_public_pages__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"Globally unique page slug (e.g. 'brand-compliance')","title":"Slug"},"description":"Globally unique page slug (e.g. 'brand-compliance')"}],"responses":{"200":{"description":"Full page configuration for UI rendering","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPageConfigResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/public/pages/{slug}/search":{"post":{"tags":["Public Pages API"],"summary":"Execute a Page tab search","description":"Execute a search on a specific tab of a public Page ā€” no authentication required.\n\nRoutes `tab_id` ā†’ retriever ā†’ results. Each tab can be backed by either:\n- An **internal retriever** (`retriever_id`) ā€” org-scoped, requires the page\n to be in your namespace\n- A **marketplace catalog entry** (`public_name`) ā€” proxied to the public\n marketplace API, no org context needed\n\nThe `inputs` dict is passed directly to the retriever's `input_schema`. For\nimage-based searches, pass `{\"query_image\": \"data:image/jpeg;base64,...\"}`.\n\n**Example request:**\n```json\n{\n \"tab_id\": \"evaluate\",\n \"inputs\": {\n \"query_image\": \"data:image/jpeg;base64,/9j/4AAQ...\"\n },\n \"settings\": {}\n}\n```","operationId":"execute_public_page_search_v1_public_pages__slug__search_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"Globally unique page slug","title":"Slug"},"description":"Globally unique page slug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPageSearchRequest"}}}},"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"}}}}}}},"/v1/public/pages/{slug}/gallery":{"get":{"tags":["Public Pages API"],"summary":"Get Page featured gallery","description":"Fetch featured gallery results for a public Page ā€” no authentication required.\n\nExecutes the page's `featured_gallery` retriever using `default_inputs` defined\nin the gallery configuration. Returns an empty result set if the gallery is\ndisabled or not configured.\n\nCalled automatically by `mxp.co/p/{slug}` on page load to pre-populate the\nfeatured gallery section with curated results.","operationId":"get_public_page_gallery_v1_public_pages__slug__gallery_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"Globally unique page slug","title":"Slug"},"description":"Globally unique page 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"}}}}}}},"/v1/pages":{"post":{"tags":["Pages"],"summary":"Create a Page","description":"Create a new branded Page served at `https://mxp.co/p/{slug}`.\n\nPages are multi-tab search interfaces that combine retrievers, a hero section,\nfeatured galleries, stats bars, and custom SEO ā€” all served from a globally\nunique slug. Each tab can route to an internal retriever (`retriever_id`) or a\nmarketplace catalog entry (`public_name`).\n\n**Rendering modes (in priority order):**\n1. `custom_html` ā€” raw HTML/CSS/JS in a sandboxed iframe (full control)\n2. `sections[]` ā€” slot-based composition with typed blocks (`template: \"generic\"`)\n3. Named presets ā€” `template: \"brand-compliance\"` etc. (legacy)\n\n**Slugs** are globally unique across all organizations. The page will be\naccessible at `https://mxp.co/p/{slug}` immediately after creation.\n\nWhen a retriever is published via `POST /v1/retrievers/{id}/publish`, a\ncompanion Page is auto-created at `/p/{public_name}` ā€” you don't need to call\nthis endpoint manually unless you want to customize the page further.","operationId":"create_page_v1_pages_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageRequest"}}}},"responses":{"200":{"description":"The created Page configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Pages"],"summary":"List Pages","description":"List all Pages for this organization.\n\nReturns Pages scoped to your organization and namespace. Use `template` to\nfilter to a specific rendering mode (e.g. `generic` for sections-based pages\nor `brand-compliance` for the legacy compliance template).","operationId":"list_pages_v1_pages_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results to return","default":100,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of results to skip for pagination","default":0,"title":"Offset"},"description":"Number of results to skip for pagination"},{"name":"template","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by template type (e.g. 'generic', 'brand-compliance')","title":"Template"},"description":"Filter by template type (e.g. 'generic', 'brand-compliance')"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"responses":{"200":{"description":"Paginated list of Pages for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPagesResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/pages/{page_id}":{"get":{"tags":["Pages"],"summary":"Get a Page","description":"Get a Page by its `page_id`.\n\nReturns the full configuration including tabs, sections, hero, gallery,\ntheme, and SEO settings.","operationId":"get_page_v1_pages__page_id__get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page ID (e.g. pg_abc123def456)","title":"Page Id"},"description":"Page ID (e.g. pg_abc123def456)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"responses":{"200":{"description":"Full Page configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Pages"],"summary":"Update a Page","description":"Partially update a Page configuration.\n\nAll fields are optional ā€” only the fields you provide are updated. Omitted\nfields retain their current values.\n\nIf you update `slug`, it must be globally unique. If you update `tabs`, all\n`retriever_id` references are re-validated against your organization.","operationId":"update_page_v1_pages__page_id__patch","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page ID (e.g. pg_abc123def456)","title":"Page Id"},"description":"Page ID (e.g. pg_abc123def456)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePageRequest"}}}},"responses":{"200":{"description":"Updated Page configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Pages"],"summary":"Delete a Page","description":"Delete a Page permanently.\n\nThe slug is freed immediately and can be reused. The page will stop\nbeing served at `https://mxp.co/p/{slug}` within seconds.","operationId":"delete_page_v1_pages__page_id__delete","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page ID (e.g. pg_abc123def456)","title":"Page Id"},"description":"Page ID (e.g. pg_abc123def456)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/health/liveness":{"get":{"tags":["Health","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"}}}}}}},"/v1/health/beat":{"get":{"tags":["Health","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"}}}}}}},"/v1/health":{"get":{"tags":["Health","Health"],"summary":"Healthcheck","description":"Health check endpoint.","operationId":"healthcheck_v1_health_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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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 ā€” 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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"patch":{"tags":["Collection Lifecycle"],"summary":"Transition Lifecycle","description":"Transition a collection's storage tier. 'cold' evicts from Qdrant (vectors searchable via S3 Vectors). 'active' rehydrates back to Qdrant. '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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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:\n ```json\n {\n \"filters\": {\"must\": [{\"key\": \"metadata.status\", \"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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:\n ```json\n {\n \"filters\": {\"must\": [{\"key\": \"metadata.status\", \"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/collections/{collection_identifier}/documents":{"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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āš™ļø **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āš ļø **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šŸ“Š **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šŸ” **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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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).","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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\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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/benchmarks":{"post":{"tags":["Retriever Benchmarks","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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"get":{"tags":["Retriever Benchmarks","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/benchmarks/{benchmark_id}":{"get":{"tags":["Retriever Benchmarks","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"delete":{"tags":["Retriever Benchmarks","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRetrieverRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRetrieverResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"patch":{"tags":["Retrievers"],"summary":"Patch Retriever","description":"Update a retriever's metadata.\n\nOnly metadata fields can be updated:\n- name: Rename the retriever\n- description: Update the description\n- tags: Update tags for organization\n- display_config: Update display configuration\n\nCore logic (input_schema, stages, collection_ids) is immutable.\nTo modify core logic, use POST /{retriever_id}/clone instead.","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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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","default":false,"title":"Return Presigned Urls"}},{"name":"return_vectors","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Return Vectors"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/interactions":{"post":{"tags":["Retriever Interactions"],"summary":"Create Interaction","description":"Record a search interaction (view, click, feedback, etc.).","operationId":"create_interaction_v1_retrievers_interactions_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/evaluations/datasets":{"post":{"tags":["Retriever Evaluations","Evaluation Datasets"],"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"get":{"tags":["Retriever Evaluations","Evaluation Datasets"],"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/evaluations/datasets/{dataset_identifier}":{"get":{"tags":["Retriever Evaluations","Evaluation Datasets"],"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/{retriever_id}/evaluations":{"post":{"tags":["Retriever Evaluations","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"get":{"tags":["Retriever Evaluations","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/retrievers/{retriever_id}/evaluations/{evaluation_id}":{"get":{"tags":["Retriever Evaluations","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/organizations/credits":{"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/organizations/users":{"post":{"tags":["Organization Users"],"summary":"Create User","description":"Create a new organization user.","operationId":"create_user_v1_organizations_users_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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šŸ”’ 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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"delete":{"tags":["Organization API Keys"],"summary":"Delete Api Key","description":"Revoke an API key.\n\nšŸ”’ The \"admin-key\" is protected and cannot be deleted.","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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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šŸ”’ 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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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\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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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 (requires explicit enable)\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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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-Id: 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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/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"}}}}}}},"/v1/marketplace/listings":{"post":{"tags":["Marketplace","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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/marketplace/listings/{listing_id}":{"patch":{"tags":["Marketplace","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"delete":{"tags":["Marketplace","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/marketplace/listings/{listing_id}/publish":{"patch":{"tags":["Marketplace","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/marketplace/catalog":{"get":{"tags":["Marketplace","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"}}}}}}},"/v1/marketplace/catalog/{public_name}":{"get":{"tags":["Marketplace","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"}}}}}}},"/v1/marketplace/catalog/{public_name}/execute":{"post":{"tags":["Marketplace","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"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"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"}}}}}}},"/v1/marketplace/catalog/{public_name}/config":{"get":{"tags":["Marketplace","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"}}}}}}},"/v1/marketplace/catalog/{public_name}/verify":{"post":{"tags":["Marketplace","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"}}}}}}},"/v1/marketplace/catalog/{public_name}/template":{"get":{"tags":["Marketplace","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"}}}}}}},"/v1/marketplace/subscriptions":{"post":{"tags":["Marketplace","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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"get":{"tags":["Marketplace","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/marketplace/subscriptions/{subscription_id}":{"get":{"tags":["Marketplace","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"delete":{"tags":["Marketplace","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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 āš ļø 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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/plugins":{"get":{"tags":["Plugins"],"summary":"List plugins in organization","description":"List all custom plugins uploaded to the organization.\n\nThese plugins are available to all namespaces within the organization.","operationId":"list_plugins_v1_plugins_get","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__plugins__models__PluginListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plugins/{plugin_id}":{"get":{"tags":["Plugins"],"summary":"Get plugin details","description":"Get detailed information about a specific plugin.","operationId":"get_plugin_v1_plugins__plugin_id__get","parameters":[{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__plugins__models__PluginDetailResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin not found","content":{"application/json":{"example":{"detail":"Plugin not found: my_plugin_1_0_0"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Plugins"],"summary":"Delete a plugin","description":"Delete a custom plugin from the organization.\n\nThis will:\n1. Delete the plugin archive from S3\n2. Remove the plugin metadata from MongoDB\n\nNote: If the plugin is deployed to any namespaces, you should undeploy it first.","operationId":"delete_plugin_v1_plugins__plugin_id__delete","parameters":[{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__plugins__models__PluginDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin 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"}}}}}}},"/v1/plugins/uploads":{"post":{"tags":["Plugins"],"summary":"Generate presigned URL for plugin upload","description":"Generate a presigned URL for uploading a plugin archive directly to S3.\n\n**This is the recommended upload method** - it avoids streaming large files\nthrough the API server.\n\n**Workflow:**\n1. Call this endpoint with plugin metadata ā†’ Returns presigned_url + upload_id\n2. PUT the plugin archive to presigned_url (Content-Type: application/zip)\n3. Call POST /plugins/uploads/{upload_id}/confirm to validate and create plugin\n\n**Requirements:**\n- Plugin name+version must not already exist in the organization\n- Archive must be .zip format containing manifest.py and pipeline.py\n (Ray Serve working_dir only supports .zip for remote URIs)\n\n**Response:**\n- `upload_id`: Use this when confirming the upload\n- `presigned_url`: PUT your .zip archive to this URL\n- `expires_at`: URL expires after this time (default: 1 hour)\n\n---\n\n## Plugin Security Requirements\n\nPlugins are scanned for security violations before upload is confirmed.\nThe following restrictions apply to all Python code in your plugin.\n\n### Allowed Imports (Recommended)\n\nThese libraries are safe to use in your plugins:\n\n| Category | Libraries |\n|----------|-----------|\n| **Data Processing** | `numpy`, `pandas`, `polars`, `pyarrow` |\n| **ML/AI** | `torch`, `transformers`, `sentence_transformers`, `onnxruntime`, `safetensors` |\n| **Image Processing** | `PIL`/`pillow`, `cv2`/`opencv-python`, `imageio` |\n| **Audio/Video** | `librosa`, `soundfile`, `ffmpeg-python` |\n| **HTTP Clients** | `requests`, `httpx`, `aiohttp` |\n| **Utilities** | `json`, `re`, `typing`, `dataclasses`, `pydantic`, `logging` |\n| **Mixpeek SDK** | `shared.models.loader.load_namespace_model` |\n\n### Forbidden Imports (Will Fail Validation)\n\nThese imports are blocked for security reasons:\n\n| Category | Blocked |\n|----------|---------|\n| **Process Execution** | `subprocess`, `os.system`, `os.popen`, `os.spawn*`, `os.exec*` |\n| **Low-level Access** | `ctypes`, `pty`, `fcntl`, `resource` |\n| **Concurrency** | `multiprocessing`, `threading` (use Ray instead) |\n| **Network** | `socket` (use `requests`/`httpx` instead) |\n| **Legacy** | `commands`, `popen2` |\n\n### Forbidden Builtins (Will Fail Validation)\n\nThese built-in functions cannot be used:\n\n- `eval()`, `exec()`, `compile()` - Dynamic code execution\n- `open()` - Direct file access (use provided APIs)\n- `__import__()` - Dynamic imports\n- `globals()`, `locals()`, `vars()` - Namespace manipulation\n- `setattr()`, `delattr()` - Attribute mutation\n\n### Forbidden Module Functions\n\n| Module | Blocked Functions |\n|--------|-------------------|\n| `os` | `system`, `popen`, `spawn`, `exec`, `fork`, `kill`, `killpg` |\n| `importlib` | `import_module`, `__import__` |\n| `pickle` | `loads`, `load` (arbitrary code execution risk) |\n| `marshal` | `loads`, `load` |\n\n### Warning Patterns (May Fail in Strict Mode)\n\nThese patterns generate warnings:\n- `pickle`, `marshal`, `shelve` usage\n- Dunder attribute access: `__builtins__`, `__class__`, `__bases__`, `__subclasses__`, `__mro__`, `__code__`, `__globals__`","operationId":"generate_upload_url_v1_plugins_uploads_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__plugins__models__CreatePluginUploadRequest"}}}},"responses":{"200":{"description":"Presigned URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__plugins__models__PluginPresignedURLResponse"},"example":{"upload_id":"plu_abc123xyz789","presigned_url":"https://s3.amazonaws.com/bucket/...","s3_key":"org_xxx/plugin_custom/plu_abc123xyz789/my_plugin_1_0_0.zip","expires_at":"2024-01-15T11:30:00Z","organization_id":"org_xxx","name":"my_plugin","version":"1.0.0"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"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":"Plugin already exists"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plugins/uploads/{upload_id}/confirm":{"post":{"tags":["Plugins"],"summary":"Confirm plugin upload","description":"Confirm a plugin upload after the archive has been uploaded to S3.\n\n**IMPORTANT:** This endpoint MUST be called after uploading to the presigned URL.\nS3 presigned URLs have no callback mechanism, so the API cannot detect when\nyour upload completes. You must explicitly confirm to:\n- Verify the file exists in S3\n- Validate archive structure (manifest.py, pipeline.py required)\n- Run security scan (see POST /plugins/uploads for security requirements)\n- Create the plugin record\n\n**Optional integrity checks:**\n- `etag`: S3 ETag from upload response header (recommended)\n- `file_size_bytes`: Expected file size for validation\n\n**On Success:**\n- Plugin is created with organization scope\n- Returns plugin_id and feature_uri for use in collections\n\n**On Security Violation:**\n- Returns 400 with list of violations (file, line, column, message)\n- Common issues: forbidden imports (subprocess, ctypes), forbidden builtins (eval, exec, open)\n- See POST /plugins/uploads documentation for full list of security requirements","operationId":"confirm_upload_v1_plugins_uploads__upload_id__confirm_post","parameters":[{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","title":"Upload Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ConfirmPluginUploadRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Upload confirmed and plugin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPluginUploadResponse"},"example":{"success":true,"upload_id":"plu_abc123xyz789","plugin_id":"my_plugin_1_0_0","validation_status":"passed","deployment_status":"pending","feature_uri":"mixpeek://my_plugin@1.0.0","s3_archive_url":"s3://bucket/..."}}}},"400":{"description":"Validation failed or upload expired"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Upload not found or S3 object missing"},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/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 ā†’ Returns presigned_url + upload_id\n2. PUT presigned_url with model archive (client uploads directly to S3)\n3. POST /models/uploads/{upload_id}/confirm ā†’ Validates and creates model\n\nThe model will be stored at the organization level and can be enabled\nin any namespace within the organization.","operationId":"generate_upload_url_v1_models_uploads_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Upload a custom plugin","description":"Upload a custom plugin to the namespace.\n\n**Availability:**\n- All accounts can upload plugins for batch processing (default quota: 10 plugins)\n- Enterprise accounts get higher quotas and realtime inference support\n\n**Requirements:**\n- Plugin archive must be a valid .zip file\n- Archive must contain `manifest.py` and `pipeline.py`\n- Plugin code must pass security scan\n\n**Archive Structure:**\n```\nmy_plugin/\nā”œā”€ā”€ manifest.py # Required: Feature definitions\nā”œā”€ā”€ pipeline.py # Required: Pipeline orchestration\nā”œā”€ā”€ batch.py # Optional: Custom batch services\nā”œā”€ā”€ realtime.py # Optional: Real-time inference (Enterprise only)\nā””ā”€ā”€ processors/ # Optional: Custom processors\n ā””ā”€ā”€ *.py\n```\n\n**Response:**\n- `validation_status`: \"passed\" or \"failed\"\n- `deployment_status`: \"deployed\", \"pending\", or \"failed\"\n- `feature_uri`: URI to use the plugin (e.g., \"mixpeek://my_plugin@v1\")","operationId":"upload_plugin_v1_namespaces__namespace_id__plugins_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_plugin_v1_namespaces__namespace_id__plugins_post"}}}},"responses":{"200":{"description":"Plugin uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginUploadResponse"},"example":{"success":true,"plugin_id":"my_plugin_1_0_0","validation_status":"passed","deployment_status":"deployed","feature_uri":"mixpeek://my_plugin@1.0.0","s3_archive_url":"s3://mixpeek-plugins/ns_abc123/plugins/my_plugin_1_0_0.tar.gz"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Plugin quota exceeded","content":{"application/json":{"example":{"detail":{"message":"Plugin quota exceeded (10/10)","type":"QuotaExceededError","details":{"current_count":10,"max_allowed":10}}}}}},"404":{"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":"Plugin already exists","content":{"application/json":{"example":{"detail":"Plugin my_plugin@1.0.0 already exists in this namespace"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Custom Plugins (Namespace)"],"summary":"List plugins in namespace","description":"List all custom plugins uploaded to the namespace.","operationId":"list_plugins_v1_namespaces__namespace_id__plugins_get","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/available":{"get":{"tags":["Custom Plugins (Namespace)"],"summary":"List available org plugins","description":"List all org-level plugins that can be enabled for this namespace.\n\nThis returns all plugins uploaded to the organization with their enable status\nfor the current namespace.\n\n**Use this to:**\n- See what org plugins are available to enable\n- Check which plugins are already enabled for this namespace","operationId":"list_available_org_plugins_v1_namespaces__namespace_id__plugins_available_get","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"List of available org plugins","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableOrgPluginsResponse"},"example":{"success":true,"plugins":[{"plugin_id":"my_plugin_1_0_0","name":"my_plugin","version":"1.0.0","description":"Custom embedder plugin","feature_uri":"mixpeek://my_plugin@1.0.0","validation_status":"passed","enabled_in_namespace":false,"created_at":"2024-01-15T10:30:00Z"}],"total":1,"organization_id":"org_xxx","namespace_id":"ns_xxx"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/{plugin_id}":{"get":{"tags":["Custom Plugins (Namespace)"],"summary":"Get plugin details","description":"Get detailed information about a specific plugin.","operationId":"get_plugin_v1_namespaces__namespace_id__plugins__plugin_id__get","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"return_presigned_urls","in":"query","required":false,"schema":{"type":"boolean","description":"Generate a presigned download URL for the plugin archive (valid for 1 hour)","default":false,"title":"Return Presigned Urls"},"description":"Generate a presigned download URL for the plugin archive (valid for 1 hour)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginDetailResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin not found","content":{"application/json":{"example":{"detail":"Plugin not found: my_plugin_1_0_0"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Custom Plugins (Namespace)"],"summary":"Delete a plugin","description":"Delete a custom plugin from the namespace.\n\n**Security:** Users can only delete plugins in their own namespace.\n\n**What happens:**\n1. If deployed (Enterprise): Queues Ray Serve deployment removal via blue-green rollout\n2. Removes plugin from namespace's feature extractors\n3. Deletes the plugin archive from S3\n4. Removes the plugin metadata from MongoDB\n\n**Response:**\n- `deployment_removed`: True if a Ray Serve deployment was queued for removal\n- Blue-green rollout completes within 5 minutes for deployed plugins","operationId":"delete_plugin_v1_namespaces__namespace_id__plugins__plugin_id__delete","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Plugin deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginDeleteResponse"},"examples":{"batch_only":{"value":{"success":true,"plugin_id":"my_plugin_1_0_0","message":"Plugin my_plugin_1_0_0 deleted successfully.","deployment_removed":false}},"realtime_deployed":{"value":{"success":true,"plugin_id":"my_plugin_1_0_0","message":"Plugin my_plugin_1_0_0 deleted. Ray Serve deployment queued for removal (blue-green rollout will complete within 5 minutes).","deployment_removed":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin not found","content":{"application/json":{"example":{"detail":"Plugin not found: my_plugin_1_0_0"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/{plugin_id}/deploy":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Deploy or redeploy a plugin","description":"Deploy a plugin for use in the namespace.\n\n**Deployment Types:**\n- `batch_only`: All accounts - plugin available for batch processing\n- `realtime`: Enterprise only - plugin deployed via GKE RayService rolling update\n\nPlugins with `realtime.py` require dedicated infrastructure (Enterprise). They are\nqueued and rolled out via GKE RayService rolling deployment. Non-enterprise accounts\ncan still use batch-only plugins and reference existing feature URIs.\n\n**Response:**\n- `status`: \"queued\", \"deployed\", or \"batch_only\"\n- `deployment_type`: \"batch_only\" or \"realtime\"\n- `route_prefix`: HTTP route for realtime plugins (Enterprise only)","operationId":"deploy_plugin_v1_namespaces__namespace_id__plugins__plugin_id__deploy_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"deployment_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployment Type"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Plugin deployed successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Deploy Plugin V1 Namespaces Namespace Id Plugins Plugin Id Deploy Post"},"examples":{"queued":{"value":{"status":"queued","message":"Plugin queued for deployment. Deployment will start within 30 seconds.","deployment_name":"custom_plugin_my_plugin_1_0_0","route_prefix":"/inference/custom_plugin_my_plugin_1_0_0","estimated_completion_seconds":210,"queue_position":1,"deployment_method":"anyscale_blue_green","status_endpoint":"/namespaces/ns_xxx/plugins/my_plugin_1_0_0/status"}},"batch_only_no_realtime":{"value":{"status":"deployed","deployment_type":"batch_only","message":"Plugin deployed for batch processing (no realtime endpoint)"}},"batch_only_requires_enterprise":{"value":{"status":"batch_only","deployment_type":"batch_only","message":"Plugin has realtime capabilities but namespace requires dedicated infrastructure for realtime deployment. Plugin is available for batch processing.","realtime_available":false,"upgrade_url":"https://mixpeek.com/pricing/enterprise"}}}}}},"400":{"description":"Plugin not validated"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin not found"},"500":{"description":"Deployment failed"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/{plugin_id}/status":{"get":{"tags":["Custom Plugins (Namespace)"],"summary":"Get plugin deployment status","description":"Get the current deployment status for a plugin.\n\n**Status Values:**\n- `queued`: Plugin is waiting in the deployment queue. Deployment will start within 30 seconds.\n- `pending`: Deployment has been triggered, waiting for Anyscale to start.\n- `in_progress`: Blue-green deployment in progress. New replicas are being created.\n- `deployed`: Plugin successfully deployed and ready for realtime inference.\n- `failed`: Deployment failed. Check the error field for details.\n- `not_deployed`: Plugin has not been deployed for realtime inference (batch-only).\n\n**Polling Recommendation:**\nAfter deploying a plugin, poll this endpoint every 10-15 seconds to check status.\nDeployment typically completes within 3-5 minutes.","operationId":"get_deployment_status_v1_namespaces__namespace_id__plugins__plugin_id__status_get","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Deployment status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginStatusResponse"},"examples":{"queued":{"value":{"plugin_id":"my_plugin_1_0_0","namespace_id":"ns_xxx","status":"queued","message":"Plugin is queued for deployment. Deployment will start within 30 seconds.","estimated_completion_seconds":210}},"deployed":{"value":{"plugin_id":"my_plugin_1_0_0","namespace_id":"ns_xxx","status":"deployed","message":"Plugin successfully deployed and ready for realtime inference.","deployed":true,"route_prefix":"/inference/custom_plugin_my_plugin_1_0_0","feature_uri":"mixpeek://my_plugin@1.0.0"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin 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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/{plugin_id}/realtime/test":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Test plugin realtime inference","description":"Test a plugin's realtime inference endpoint and return the raw response.\n\n**Use this to debug custom plugin inference** ā€” especially when retrievers fail\nwith \"Cannot extract dense vector\" errors. This endpoint calls the same inference\npath that retrievers use, but returns the raw response instead of trying to\nextract an embedding.\n\n**What to check in the response:**\n- `response_type`: Should be \"dict\" for embedding plugins\n- `response_keys`: Should contain \"embedding\" or similar key\n- `raw_response`: The actual data your plugin returns\n\n**Example:**\n```json\nPOST /{plugin_id}/realtime/test\n{\"inputs\": {\"text\": \"hello world\"}}\n```","operationId":"test_realtime_inference_v1_namespaces__namespace_id__plugins__plugin_id__realtime_test_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginRealtimeTestRequest"}}}},"responses":{"200":{"description":"Inference test result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginRealtimeTestResponse"},"examples":{"success":{"value":{"status":"success","inference_name":"custom_plugin_my_embedder_1_0_0","raw_response":{"embedding":[0.1,0.2,0.3]},"response_type":"dict","response_keys":["embedding"],"message":"Inference call to 'custom_plugin_my_embedder_1_0_0' succeeded"}},"error":{"value":{"status":"error","inference_name":"custom_plugin_my_embedder_1_0_0","error":"Connection refused","message":"Inference call to 'custom_plugin_my_embedder_1_0_0' failed"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Plugin 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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/{plugin_id}/undeploy":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Undeploy a plugin","description":"Remove a plugin deployment from the namespace's Ray cluster.\n\nThis will:\n1. Remove the Ray Serve deployment (if realtime)\n2. Update deployment status in MongoDB to deployed=False\n\nThe plugin archive remains in S3 and can be redeployed.","operationId":"undeploy_plugin_v1_namespaces__namespace_id__plugins__plugin_id__undeploy_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Plugin undeployed successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Undeploy Plugin V1 Namespaces Namespace Id Plugins Plugin Id Undeploy 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":"Plugin 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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/reconfigure":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Reconfigure namespace Qdrant schema","description":"Reconfigure the namespace's Qdrant collection to include vectors from all deployed plugins.\n\n**When to use this:**\nAfter deploying a new plugin to a namespace that already has data (points_count > 0).\nThe auto-rebuild (Phase 1) only works on empty collections. For namespaces with existing\ndata, use this endpoint to rebuild the schema, then re-trigger batches to re-ingest.\n\n**WARNING: This is destructive!**\n- All existing Qdrant points are **deleted**\n- The collection is recreated with merged vector definitions\n- You must re-trigger batches on each collection to re-populate data\n\n**Workflow:**\n1. Deploy your new plugin: `POST /plugins/uploads/{id}/confirm`\n2. Deploy it: `POST /plugins/{id}/deploy`\n3. Reconfigure: `POST /plugins/reconfigure` with `{\"confirm\": true}`\n4. Re-trigger each collection listed in `collections_to_reprocess`\n\n**Response includes:**\n- `vectors_added`: New vector indexes added by the reconfigure\n- `vectors_total`: All vector indexes in the reconfigured collection\n- `collections_to_reprocess`: Collection IDs to re-trigger for data re-ingestion","operationId":"reconfigure_namespace_v1_namespaces__namespace_id__plugins_reconfigure_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconfigureNamespaceRequest"}}}},"responses":{"200":{"description":"Namespace reconfigured successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconfigureNamespaceResponse"},"examples":{"reconfigured":{"value":{"namespace_id":"ns_abc123","status":"reconfigured","previous_points_count":1500,"vectors_added":["fashionsiglip_v1_embedding"],"vectors_total":["multilingual_e5_large_instruct_v1","fashionsiglip_v1_embedding"],"collections_to_reprocess":["col_xxx","col_yyy"],"message":"Qdrant collection reconfigured with 1 new vector(s). 1500 points were deleted. Re-trigger batches on the listed collections to re-ingest data with the new vectors."}},"no_changes":{"value":{"namespace_id":"ns_abc123","status":"no_changes_needed","previous_points_count":1500,"vectors_added":[],"vectors_total":["multilingual_e5_large_instruct_v1"],"collections_to_reprocess":["col_xxx"],"message":"All plugin vectors already exist in the Qdrant schema. No reconfiguration needed."}}}}}},"400":{"description":"confirm=true not set"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Namespace or Qdrant collection 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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/uploads":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Generate presigned URL for plugin upload","description":"Generate a presigned URL for uploading a plugin archive directly to S3.\n\n**This is the recommended upload method** - it avoids streaming large files\nthrough the API server.\n\n**Availability:**\n- All accounts can upload plugins for batch processing (default quota: 10 plugins)\n- Enterprise accounts get higher quotas and realtime inference support\n\n**Workflow:**\n1. Call this endpoint with plugin metadata ā†’ Returns presigned_url + upload_id\n2. PUT the plugin archive to presigned_url (Content-Type: application/zip)\n3. Call POST /uploads/{upload_id}/confirm to validate and deploy\n\n**Requirements:**\n- Plugin name+version must not already exist\n- Must be within plugin quota\n\n**Response:**\n- `upload_id`: Use this when confirming the upload\n- `presigned_url`: PUT your .zip archive to this URL\n- `expires_at`: URL expires after this time (default: 1 hour)","operationId":"generate_upload_url_v1_namespaces__namespace_id__plugins_uploads_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__namespaces__plugins__models__CreatePluginUploadRequest"}}}},"responses":{"200":{"description":"Presigned URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginPresignedURLResponse"},"example":{"upload_id":"plu_abc123xyz789","presigned_url":"https://s3.amazonaws.com/bucket/...","s3_key":"ns_xxx/plugins/plu_abc123xyz789/my_plugin_1_0_0.zip","expires_at":"2024-01-15T11:30:00Z","namespace_id":"ns_xxx","name":"my_plugin","version":"1.0.0"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Plugin quota exceeded"},"404":{"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":"Plugin already exists"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/uploads/{upload_id}/confirm":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Confirm plugin upload","description":"Confirm a plugin upload after the archive has been uploaded to S3.\n\n**IMPORTANT:** This endpoint MUST be called after uploading to the presigned URL.\nS3 presigned URLs have no callback mechanism, so the API cannot detect when\nyour upload completes. You must explicitly confirm to:\n- Verify the file exists in S3\n- Validate archive structure (`manifest.py` and `pipeline.py` required)\n- Run security scan on all `.py` files\n- Create the plugin record\n- Mark upload as COMPLETED\n\n**Optional integrity checks:**\n- `etag`: S3 ETag from upload response header (recommended)\n- `file_size_bytes`: Expected file size for validation\n\n**On Success:**\n- Plugin is created with status \"pending\" deployment\n- Returns `plugin_id` and `feature_uri` for use in collections\n\n**Security scanner rules:**\n- Blocked imports: `subprocess`, `ctypes`, `socket`, `multiprocessing`, `threading`\n- Blocked calls: `os.system()`, `os.popen()`, `os.exec*()`, `eval()`, `exec()`, `open()`\n- `import os` is **allowed** ā€” only the dangerous functions above are blocked\n- `getattr()`, `hasattr()`, `os.environ`, `os.path` are all allowed\n\n**manifest.py `features` format:** Use these exact key names or the collection will be\ncreated with no vector indexes (no error is returned, but 0 documents will be indexed):\n```json\n{\n \"feature_type\": \"embedding\",\n \"feature_name\": \"my_embedding\",\n \"embedding_dim\": 768,\n \"distance_metric\": \"cosine\"\n}\n```","operationId":"confirm_upload_v1_namespaces__namespace_id__plugins_uploads__upload_id__confirm_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","title":"Upload Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ConfirmPluginUploadRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Upload confirmed and plugin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPluginUploadResponse"},"example":{"success":true,"upload_id":"plu_abc123xyz789","plugin_id":"my_plugin_1_0_0","validation_status":"passed","deployment_status":"pending","feature_uri":"mixpeek://my_plugin@1.0.0","s3_archive_url":"s3://bucket/..."}}}},"400":{"description":"Validation failed or upload expired"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Upload not found or S3 object missing"},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/org/{plugin_id}/enable":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Enable org plugin for namespace","description":"Enable an org-level plugin for this namespace.\n\nThis:\n1. Adds the plugin to the namespace's feature_extractors array\n2. Optionally deploys the plugin to Ray (if deploy=True)\n\nAfter enabling, the plugin can be used when creating collections in this namespace.\n\n**Note:** The plugin must exist at the organization level (uploaded via POST /v1/plugins/uploads).","operationId":"enable_org_plugin_v1_namespaces__namespace_id__plugins_org__plugin_id__enable_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EnableOrgPluginRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Plugin enabled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableOrgPluginResponse"},"example":{"success":true,"plugin_id":"my_plugin_1_0_0","namespace_id":"ns_xxx","feature_uri":"mixpeek://my_plugin@1.0.0","message":"Plugin my_plugin@1.0.0 enabled for namespace","deployment_status":"deployed"}}}},"400":{"description":"Plugin 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 plugin 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"}}}}}}},"/v1/namespaces/{namespace_id}/plugins/org/{plugin_id}/disable":{"post":{"tags":["Custom Plugins (Namespace)"],"summary":"Disable org plugin for namespace","description":"Disable an org-level plugin for this namespace.\n\nThis:\n1. Removes the plugin from the namespace's feature_extractors array\n2. Undeploys from Ray if deployed\n3. Removes the namespace-specific plugin tracking record\n\n**Warning:** Collections using this plugin may no longer function correctly.","operationId":"disable_org_plugin_v1_namespaces__namespace_id__plugins_org__plugin_id__disable_post","parameters":[{"name":"namespace_id","in":"path","required":true,"schema":{"type":"string","title":"Namespace Id"}},{"name":"plugin_id","in":"path","required":true,"schema":{"type":"string","title":"Plugin Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"responses":{"200":{"description":"Plugin disabled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableOrgPluginResponse"},"example":{"success":true,"plugin_id":"my_plugin_1_0_0","namespace_id":"ns_xxx","message":"Plugin my_plugin@1.0.0 disabled for namespace"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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 plugin 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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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:**\n- `continuous`: Real-time monitoring with configurable polling interval\n- `one_time`: Single bulk import, then sync stops\n- `scheduled`: Polling-based batch imports at fixed intervals","operationId":"create_sync_configuration_v1_buckets__bucket_id__syncs_post","parameters":[{"name":"bucket_id","in":"path","required":true,"schema":{"type":"string","title":"Bucket Id"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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.","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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/buckets/{bucket_identifier}/batches/{batch_id}/submit":{"post":{"tags":["Bucket Batches"],"summary":"Submit Batch for Processing","description":"Submit a batch for asynchronous processing. The batch must be in 'pending' 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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/buckets/{bucket_identifier}/batches/{batch_id}/tiers/{tier_num}/retry-qdrant-write":{"post":{"tags":["Bucket Batches"],"summary":"Retry Qdrant Write from S3","description":"Retry Qdrant write by reading processed output from S3. Use when validation detects 'qdrant_write_failed'.","operationId":"retry_qdrant_write_v1_buckets__bucket_identifier__batches__batch_id__tiers__tier_num__retry_qdrant_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)."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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 Qdrant 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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/batches/list":{"post":{"tags":["Batches"],"summary":"List All Batches","description":"List batches across all buckets. Supports status and namespace filters.","operationId":"list_all_batches_v1_batches_list_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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 ā†’ Get presigned URL\n 2. PUT file to presigned URL ā†’ Upload directly to S3\n 3. Call confirm endpoint ā†’ 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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmUploadRequest"}}}},"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/notifications/preferences":{"get":{"tags":["Notifications"],"summary":"Get Preferences","description":"Get notification preferences for the organization.","operationId":"get_preferences_v1_notifications_preferences_get","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"put":{"tags":["Notifications"],"summary":"Update Preferences","description":"Update notification preferences for the organization.","operationId":"update_preferences_v1_notifications_preferences_put","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}},"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/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).\nOnly a restricted set of stages can be advanced this way.","operationId":"advance_funnel_stage_v1_notifications_funnel_advance_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."}],"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"}}}}}}},"/v1/taxonomies":{"post":{"tags":["Taxonomies"],"summary":"Create Taxonomy","description":"Create a taxonomy and return the created resource.","operationId":"create_taxonomy_v1_taxonomies_post","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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_...)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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_...)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/taxonomies/execute/{taxonomy_identifier}":{"post":{"tags":["Taxonomies"],"summary":"Test taxonomy configuration (validation only)","description":"āš ļø VALIDATION ENDPOINT ONLY - Not for production enrichment!\n\nThis endpoint validates taxonomy configuration with 1-5 sample documents.\nResults are returned immediately and NOT persisted to any collection.\n\nāŒ 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āœ… 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šŸ“š 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","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},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/taxonomies/{taxonomy_id}/analytics/transitions":{"post":{"tags":["Taxonomy Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/taxonomies/{taxonomy_id}/analytics/paths":{"post":{"tags":["Taxonomy Analytics","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ā†’B 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 ā†’ followup ā†’ proposal ā†’ closed_won\n- Discover: Others skip steps: inquiry ā†’ proposal ā†’ closed_won\n- Discover: Fast track: inquiry ā†’ closed_won\n\n**Content Editorial Paths:**\n- Question: Common paths from \"draft\" to \"published\"?\n- Discover: draft ā†’ review ā†’ edit ā†’ review ā†’ published\n- Discover: draft ā†’ review ā†’ published (expedited)\n- Discover: Paths that loop back (draft ā†’ review ā†’ draft ā†’ review)\n\n**Compliance Resolution Paths:**\n- Question: How do violations get resolved?\n- Discover: violation ā†’ investigated ā†’ remediated ā†’ resolved\n- Discover: violation ā†’ false_positive ā†’ closed\n- Discover: Escalation paths: violation ā†’ escalated ā†’ legal_review ā†’ 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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/taxonomies/{taxonomy_id}/analytics/available-steps":{"get":{"tags":["Taxonomy Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/alerts":{"post":{"tags":["Alerts","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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/alerts/{alert_identifier}":{"get":{"tags":["Alerts","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"patch":{"tags":["Alerts","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"delete":{"tags":["Alerts","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/alerts/list":{"post":{"tags":["Alerts","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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/alerts/{alert_identifier}/executions":{"get":{"tags":["Alerts","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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/alerts/executions":{"get":{"tags":["Alerts","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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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.","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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\n Note: Output collections created by the cluster are NOT deleted as they\n contain user data and should persist independently.\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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers":{"post":{"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/list":{"post":{"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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/{trigger_id}":{"get":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"patch":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"delete":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/{trigger_id}/pause":{"post":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/{trigger_id}/resume":{"post":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/{trigger_id}/execute":{"post":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/triggers/{trigger_id}/history":{"get":{"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":0},{"type":"null"}],"title":"Offset"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"include_total","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Total"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}},"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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/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":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/performance":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/stages":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/signals":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/cache-performance":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/analyze-tuning":{"post":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/retrievers/{retriever_id}/slow-queries":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/engine":{"get":{"tags":["Analytics","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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/engine/stages":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/engine/extractors":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/batches/{batch_id}/diagnostics":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/engine/bottlenecks":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/performance/engine/slow-operations":{"get":{"tags":["Analytics","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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/usage/summary":{"get":{"tags":["Analytics","Analytics","Analytics - Usage"],"summary":"Get Usage Summary","description":"Get usage summary for billing.\n\nReturns usage statistics for the namespace including:\n- Total API requests\n- Compute usage (seconds)\n- Storage usage (bytes)\n- Total cost\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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/extractors/performance":{"get":{"tags":["Analytics","Analytics","Analytics - Extractors"],"summary":"Get Extractor Performance","description":"Get feature extraction performance metrics.\n\nReturns performance metrics for feature extractors including:\n- Total executions per extractor\n- Average duration\n- P95/P99 latencies\n- Success/failure rates\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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/inference/performance":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/fields/most-queried":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/queries/slow":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/fields/performance":{"get":{"tags":["Analytics","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 Ɨ latency)\n- Sorted by priority score\n\n**Index Priority Score:**\nHigher scores indicate fields where indexing would have greatest impact.\nScore = (query count) Ɨ (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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/indexes/compound-patterns":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/indexes/recommendations":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/namespaces/summary":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/indexes/suggestions":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/indexes/usage":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/storage":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/upload-performance":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/sync-performance":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/health":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/usage":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/buckets/{bucket_id}/sync-comparison":{"get":{"tags":["Analytics","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)"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/collections/{collection_id}/overview":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/collections/{collection_id}/growth":{"get":{"tags":["Analytics","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"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/collections/{collection_id}/extractors":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/collections/{collection_id}/latency":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/collections/{collection_id}/failures":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/clusters/{cluster_id}/execution-history":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/clusters/{cluster_id}/failures":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/taxonomies/{taxonomy_id}/assignments":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/taxonomies/{taxonomy_id}/confidence":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/taxonomies/{taxonomy_id}/labels":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/analytics/taxonomies/{taxonomy_id}/enrichments":{"get":{"tags":["Analytics","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"}},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.","examples":["Bearer YOUR_API_KEY","Bearer YOUR_STRIPE_API_KEY"],"title":"Authorization"},"description":"REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings."},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-Namespace","in":"header","required":false,"schema":{"type":"string","description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'","examples":["ns_abc123def456","production","my-namespace"],"title":"X-Namespace"},"description":"REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'"}],"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"}}}}}}},"/v1/internal/batches/{batch_id}/tiers/{tier_num}/complete":{"post":{"tags":["Private"],"summary":"Mark tier complete and trigger next tier (KISS - Engine callback)","description":"Called by Engine/BatchPoller when a tier completes. Simplified single-endpoint flow.","operationId":"complete_tier_v1_internal_batches__batch_id__tiers__tier_num__complete_post","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}},{"name":"tier_num","in":"path","required":true,"schema":{"type":"integer","title":"Tier Num"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerTierRequest"}}}},"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"}}}}}}},"/v1/internal/tasks/{task_id}/status":{"post":{"tags":["Private"],"summary":"Update task status (Engine callback)","description":"Internal endpoint for Engine to update task status after async job completion.","operationId":"update_task_status_v1_internal_tasks__task_id__status_post","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStatusUpdateRequest"}}}},"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"}}}}}}}},"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."}},"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":13,"minLength":10},{"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."},"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"]]},"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":13,"minLength":10},{"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."},"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"]]}},"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"],"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_"},"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)."}},"type":"object","title":"APIKeyUpdateRequest","description":"Partial update payload for an API key."},"AccountTier":{"type":"string","enum":["free","pro","team","enterprise"],"title":"AccountTier","description":"Account tier with monthly credit allocations.\n\nTiers:\n FREE: 1,000 credits/month - Limited modalities, shared compute\n PRO: 100,000 credits/month - All modalities, dedicated namespace\n TEAM: 1,000,000 credits/month - Shared buckets, retrieval DAGs\n ENTERPRISE: Custom credits - Dedicated Ray cluster, SLA"},"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."},"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."},"AddUserToOrganizationRequest":{"properties":{"organization_identifier":{"type":"string","title":"Organization Identifier","description":"Organization ID or name to add users to."},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Organization logo URL (e.g., from Google Favicon service). If provided and organization doesn't have a logo, this will be set."},"users":{"items":{"$ref":"#/components/schemas/UserCreateRequest"},"type":"array","minItems":1,"title":"Users","description":"List of users to add to the organization."}},"type":"object","required":["organization_identifier","users"],"title":"AddUserToOrganizationRequest","description":"Payload for adding users to an organization (private/admin endpoint).","examples":[{"logo_url":"https://www.google.com/s2/favicons?domain=example.com&sz=128","organization_identifier":"org_demo123","users":[{"email":"newuser@example.com","role":"member","user_name":"New User"}]}]},"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).","examples":[["my_collection"],["col_abc123","products"],[]]},"input_schema":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Input"},"type":"object","title":"Input Schema","description":"REQUIRED. Input schema defining expected inputs. Each key is an input name, value is a RetrieverInputSchemaField.","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"},"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":"REQUIRED. Input values matching the input_schema. These values are passed to stages for parameterization.","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":["input_schema","stages","inputs"],"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' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o'","default":"gemini-2.5-flash"},"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 tool names the agent can call. See AvailableTool enum for full list. Key tools: smart_search (natural language 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\",\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-3-5-sonnet-20241022","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"]},"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the retriever to execute. The retriever defines filters, scoring, limits.","examples":["ret_safety_search","ret_prohibited_content"]},"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","retriever_id","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"}]},"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}]},"AnthropicModel":{"type":"string","enum":["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)"},"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."},"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"},"rollback_performed":{"type":"boolean","title":"Rollback Performed","description":"Whether rollback was performed due to failure","default":false},"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 Qdrant 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 ā†’ 'Electronics' (parent) ā†’ 'Apple', 'Samsung' (children). hierarchical=False ā†’ '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 ā†’ brand clustering","hierarchical_grouping":true},{"aggregation_method":"most_frequent","attributes":["status","priority"],"description":"Order status and priority (flat)","hierarchical_grouping":false}]},"AuditAction":{"type":"string","enum":["user_created","user_updated","user_deleted","api_key_created","api_key_rotated","api_key_revoked","api_key_scope_updated","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","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"],"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\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"}},"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."},"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."},"AvailableOrgPluginItem":{"properties":{"plugin_id":{"type":"string","title":"Plugin Id","description":"Unique plugin identifier"},"name":{"type":"string","title":"Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Plugin description"},"feature_uri":{"type":"string","title":"Feature Uri","description":"Feature URI to use when enabled"},"validation_status":{"type":"string","title":"Validation Status","description":"Validation status"},"enabled_in_namespace":{"type":"boolean","title":"Enabled In Namespace","description":"Whether this plugin is enabled in the current namespace"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the plugin was created"}},"type":"object","required":["plugin_id","name","version","feature_uri","validation_status","enabled_in_namespace","created_at"],"title":"AvailableOrgPluginItem","description":"An org-level plugin available to enable for a namespace."},"AvailableOrgPluginsResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugins":{"items":{"$ref":"#/components/schemas/AvailableOrgPluginItem"},"type":"array","title":"Plugins","description":"List of available org-level plugins"},"total":{"type":"integer","title":"Total","description":"Total number of plugins"},"organization_id":{"type":"string","title":"Organization Id","description":"Organization ID"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"}},"type":"object","required":["plugins","total","organization_id","namespace_id"],"title":"AvailableOrgPluginsResponse","description":"Response listing org-level plugins available to enable."},"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 ```"},"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)"},"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"}]},"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."},"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.","examples":[{"must":[{"key":"metadata.status","value":"archived"}]}]}},"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":{"must":[{"key":"metadata.status","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},"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"}]},"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"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"OPTIONAL (defaults to DRAFT). Current processing status of the batch. Lifecycle: DRAFT ā†’ PENDING ā†’ IN_PROGRESS ā†’ 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"]},"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"]]},"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"]},"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. None if batch succeeded or is still processing. Maps error_type (category) to total count of affected documents across all tiers. 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}]},"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 via Celery task (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":{"additionalProperties":true,"type":"object","title":"Metadata","description":"OPTIONAL. User-defined metadata for the batch. Arbitrary key-value pairs for user tracking and organization. Persisted with the batch and returned in API responses. Not used by the system for processing logic. Examples: campaign_id, user_email, processing_notes.","examples":[{"campaign_id":"Q4_2025","priority":"high"},{"project":"video_analysis","user_email":"user@example.com"}]},"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 ā†’ 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 ā†’ chunks ā†’ frames ā†’ scenes ā†’ 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"]},"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"]}},"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 ā†’ chunks ā†’ frames ā†’ 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 ā†’ status changes to PENDING\n 3. Each tier processes sequentially (tier 0 ā†’ tier 1 ā†’ ... ā†’ 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 ā†’ Collections (bucket as source)\n - Tier N (N > 0): Collection documents ā†’ 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."},"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."},"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":{"must":[{"key":"metadata.status","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"}]}]},"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."},"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"}]},"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 }"},"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","format":"binary","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","format":"binary","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_lint_manifest_v1_manifest_lint_post":{"properties":{"manifest_file":{"type":"string","format":"binary","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","format":"binary","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_upload_plugin_v1_namespaces__namespace_id__plugins_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Plugin archive (.tar.gz)"},"name":{"type":"string","title":"Name","description":"Plugin name (e.g., 'my_plugin')"},"version":{"type":"string","title":"Version","description":"Plugin version (e.g., '1.0.0')"},"description":{"type":"string","title":"Description","description":"Optional plugin description"}},"type":"object","required":["file","name","version"],"title":"Body_upload_plugin_v1_namespaces__namespace_id__plugins_post"},"Body_validate_manifest_v1_manifest_validate_post":{"properties":{"manifest_file":{"type":"string","format":"binary","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 ā†’ 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"},"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":"Schema definition for objects in this bucket (REQUIRED). Defines the custom fields your objects will have (blob properties, metadata structure, etc.)"},"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"}},"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 ā†’ collection ā†’ 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"}},"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"},"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)"}},"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"}},"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"}},"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"}},"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}]},"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. Supports complex logical operators (AND, OR, NOT). Example: {'must': [{'key': 'metadata.status', 'value': 'pending'}]}","examples":[{"must":[{"key":"metadata.status","value":"pending"}]},{"must":[{"gt":"2024-01-01","key":"metadata.created_at"}]}]},"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":{"must":[{"key":"metadata.status","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."},"CORSConfigurationInfo":{"properties":{"bucket":{"type":"string","title":"Bucket","description":"The object storage bucket name"},"has_cors":{"type":"boolean","title":"Has Cors","description":"Whether CORS is currently configured on the bucket"},"cors_rules":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Cors Rules","description":"The current CORS rules (if configured)"}},"type":"object","required":["bucket","has_cors"],"title":"CORSConfigurationInfo","description":"Current CORS configuration information."},"CORSConfigurationResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the CORS configuration was successful"},"bucket":{"type":"string","title":"Bucket","description":"The object storage bucket name where CORS was configured"},"applied_configuration":{"additionalProperties":true,"type":"object","title":"Applied Configuration","description":"The CORS configuration that was applied to the bucket"},"message":{"type":"string","title":"Message","description":"Human-readable status message"}},"type":"object","required":["success","bucket","applied_configuration","message"],"title":"CORSConfigurationResponse","description":"Response model for CORS configuration operations."},"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."},"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":"Celery task ID for tracking clone progress"},"cloned_resources":{"anyOf":[{"$ref":"#/components/schemas/ClonedResourceSummary"},{"type":"null"}],"description":"Summary of cloned resources (present when ready)"}},"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.","examples":[["products_v2"],["col_abc123","col_def456"]]},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/StageConfig"},"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"},"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."},"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","pattern":"^cl_[0-9]+$","title":"Cluster Id","description":"REQUIRED. Unique identifier for this cluster within the execution. Format: 'cl_' prefix followed by numeric index (e.g., 'cl_0', 'cl_1'). Used to reference this specific cluster in queries and enrichments. Consistent across executions if algorithm deterministic.","examples":["cl_0","cl_1","cl_2"]},"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]}},"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 Ɨ 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 +āˆž (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 +āˆž (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 ā†’ processing ā†’ (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]},"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]}},"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 ā†’ POST /clusters\n 2. Execute clustering ā†’ POST /clusters/{id}/execute\n 3. Poll execution status ā†’ GET /clusters/{id}/executions\n 4. View execution history ā†’ POST /clusters/{id}/executions/list\n\nStatus Lifecycle:\n pending ā†’ processing ā†’ 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"}]},"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."},"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"},"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"},"last_execution_task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Task Id","description":"Most recent task ID for this cluster"},"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."},"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.0-flash","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.0-flash","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","attribute_based"],"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\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":{"$ref":"#/components/schemas/BucketSchema-Output","description":"REQUIRED (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":{"$ref":"#/components/schemas/BucketSchema-Output","description":"REQUIRED (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"}]]},"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 currently in the collection. Automatically maintained by the system as documents are added or removed. Used for: Sorting, filtering, and pagination in list endpoints. Updated during batch processing and document operations.","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},"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","input_schema","output_schema","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 ā†’ frames ā†’ 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":{"$ref":"#/components/schemas/BucketSchema-Output","description":"REQUIRED (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":{"$ref":"#/components/schemas/BucketSchema-Output","description":"REQUIRED (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"}]]},"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},"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"}]}]]},"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","input_schema","output_schema","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."},"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."},"ConfigureCORSRequest":{"properties":{"allowed_origins":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Allowed Origins","description":"List of allowed origins for CORS. These are the frontend URLs that will be allowed to upload directly to object storage. REQUIRED. Must be valid HTTP/HTTPS URLs. Examples: ['http://localhost:8080', 'https://app.example.com']","examples":[["http://localhost:8080","http://localhost:3000"],["https://app.example.com","https://staging.example.com"]]},"allowed_methods":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Methods","description":"HTTP methods to allow for CORS requests. OPTIONAL - defaults to ['GET', 'PUT', 'POST', 'HEAD', 'DELETE'] if not provided. Common methods: GET (download), PUT (upload), POST (multipart upload), HEAD (metadata check)","examples":[["GET","PUT","POST","HEAD"],["GET","PUT","POST","HEAD","DELETE"]]},"allowed_headers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Headers","description":"Headers that are allowed in CORS requests. OPTIONAL - defaults to ['*'] (allow all headers) if not provided. Use ['*'] for maximum compatibility or specify specific headers.","examples":[["*"],["Content-Type","Authorization","X-Requested-With"]]},"expose_headers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Expose Headers","description":"Headers that browsers are allowed to access in responses. OPTIONAL - defaults to ['ETag', 'x-amz-request-id'] if not provided. 'ETag' is particularly important for upload confirmation.","examples":[["ETag"],["ETag","x-amz-request-id","Content-Length"]]},"max_age_seconds":{"anyOf":[{"type":"integer","maximum":86400.0,"minimum":0.0},{"type":"null"}],"title":"Max Age Seconds","description":"How long (in seconds) browsers should cache preflight request results. OPTIONAL - defaults to 3000 seconds (50 minutes) if not provided. Higher values reduce preflight requests but may delay policy updates.","examples":[3000,3600,7200]}},"type":"object","required":["allowed_origins"],"title":"ConfigureCORSRequest","description":"Request model for configuring CORS on object storage.\n\nThis allows administrators to configure CORS policies on the object storage\nbucket to enable browser-based uploads using presigned URLs.","examples":[{"allowed_origins":["http://localhost:8080","http://localhost:3000","http://localhost:5173"],"description":"Local development setup with multiple ports"},{"allowed_headers":["Content-Type","Authorization"],"allowed_methods":["GET","PUT","POST","HEAD"],"allowed_origins":["https://app.example.com","https://staging.example.com"],"description":"Production setup with specific headers","expose_headers":["ETag","Content-Length"],"max_age_seconds":3600},{"allowed_origins":["https://app.example.com"],"description":"Minimal configuration (uses defaults)"}]},"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."},"ConfirmPluginUploadRequest":{"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":"ConfirmPluginUploadRequest","description":"Request to confirm a plugin 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"},"ConfirmPluginUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether upload and validation succeeded"},"upload_id":{"type":"string","title":"Upload Id","description":"The upload ID"},"plugin_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plugin Id","description":"Created plugin 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"},"deployment_status":{"type":"string","enum":["deployed","pending","failed","not_deployed"],"title":"Deployment Status","description":"Deployment status"},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Feature URI for using the plugin"},"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","deployment_status"],"title":"ConfirmPluginUploadResponse","description":"Response from confirming a plugin upload."},"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]}},"type":"object","title":"ConfirmUploadRequest","description":"Request to confirm S3 upload completion and create bucket object.\n\nāš ļø 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},{"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 (if async=true)"},"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."},"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."},"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."},"CourseContentExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"course_content_extractor","title":"Extractor Type","description":"Discriminator field. Must be 'course_content_extractor'.","default":"course_content_extractor"},"target_segment_duration_ms":{"type":"integer","maximum":600000.0,"minimum":30000.0,"title":"Target Segment Duration Ms","description":"Target duration for video segments in milliseconds.","default":120000},"min_segment_duration_ms":{"type":"integer","minimum":10000.0,"title":"Min Segment Duration Ms","description":"Minimum duration for video segments in milliseconds.","default":30000},"segmentation_method":{"type":"string","enum":["scene","srt","time"],"title":"Segmentation Method","description":"Video segmentation method: 'scene', 'srt', or 'time'.","default":"scene"},"scene_detection_threshold":{"type":"number","maximum":0.9,"minimum":0.1,"title":"Scene Detection Threshold","description":"Scene detection sensitivity (0.0-1.0).","default":0.3},"use_whisper_asr":{"type":"boolean","title":"Use Whisper Asr","description":"Use Whisper ASR for transcription instead of SRT subtitles.","default":true},"expand_to_granular_docs":{"type":"boolean","title":"Expand To Granular Docs","description":"Expand each segment into multiple granular documents.","default":true},"ocr_frames_per_segment":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Ocr Frames Per Segment","description":"Number of frames to OCR per video segment.","default":3},"pdf_extraction_mode":{"type":"string","enum":["per_page","per_element"],"title":"Pdf Extraction Mode","description":"How to extract PDF content: 'per_page' or 'per_element'.","default":"per_element"},"pdf_render_dpi":{"type":"integer","maximum":300.0,"minimum":72.0,"title":"Pdf Render Dpi","description":"DPI for rendering PDF pages/elements as images.","default":150},"detect_code_in_pdf":{"type":"boolean","title":"Detect Code In Pdf","description":"Whether to detect code blocks in PDF text.","default":true},"segment_functions":{"type":"boolean","title":"Segment Functions","description":"Whether to segment code files into individual functions.","default":true},"supported_languages":{"items":{"type":"string"},"type":"array","title":"Supported Languages","description":"Programming languages to extract from code archives."},"run_text_embedding":{"type":"boolean","title":"Run Text Embedding","description":"Generate E5 text embeddings (1024D) for transcripts and text.","default":true},"run_code_embedding":{"type":"boolean","title":"Run Code Embedding","description":"Generate Jina Code embeddings (768D) for code snippets.","default":true},"run_visual_embedding":{"type":"boolean","title":"Run Visual Embedding","description":"Generate SigLIP visual embeddings (768D) for video frames.","default":true},"run_structure_embedding":{"type":"boolean","title":"Run Structure Embedding","description":"Generate DINOv2 visual structure embeddings (768D) for layout comparison.","default":true},"visual_embedding_use_case":{"type":"string","enum":["lecture","code_demo","tutorial","presentation","dynamic"],"title":"Visual Embedding Use Case","description":"Content type preset for visual embedding strategy.","default":"lecture"},"extract_screen_text":{"type":"boolean","title":"Extract Screen Text","description":"Run OCR on video frames to extract on-screen text.","default":true},"generate_thumbnails":{"type":"boolean","title":"Generate Thumbnails","description":"Generate thumbnail images for each learning unit.","default":true},"use_cdn":{"type":"boolean","title":"Use Cdn","description":"Use CDN for thumbnail delivery.","default":false},"run_vlm_frame_analysis":{"type":"boolean","title":"Run Vlm Frame Analysis","description":"Run VLM on video frame thumbnails to extract structured fields: frame_type, page_context, ui_labels, workflow_steps, config_options. Enables drift detection and UI comparison use cases.","default":false},"vlm_provider":{"type":"string","enum":["google","vllm"],"title":"Vlm Provider","description":"VLM provider: 'google' (Gemini API) or 'vllm' (local GPU with Qwen2.5-VL).","default":"google"},"vlm_model":{"type":"string","title":"Vlm Model","description":"VLM model. For google: 'gemini-2.5-flash'. For vllm: 'Qwen/Qwen2.5-VL-7B-Instruct'.","default":"gemini-2.5-flash"},"enrich_with_llm":{"type":"boolean","title":"Enrich With Llm","description":"Use Gemini to generate summaries and enhance descriptions.","default":false},"llm_prompt":{"type":"string","title":"Llm Prompt","description":"Prompt for LLM enrichment when enrich_with_llm=True.","default":"Summarize this educational content segment, highlighting key concepts."}},"type":"object","title":"CourseContentExtractorParams","description":"Parameters for the course content extractor.","examples":[{"description":"Standard video processing with all embeddings","extractor_type":"course_content_extractor","run_code_embedding":true,"run_structure_embedding":true,"run_text_embedding":true,"run_visual_embedding":true,"target_segment_duration_ms":120000}]},"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"]},"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the retriever to execute. The retriever defines filters, scoring, limits.","examples":["ret_safety_search","ret_prohibited_content"]},"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","retriever_id","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"}]},"CreateBatchRequest":{"properties":{"object_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Object Ids","description":"REQUIRED. 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. All objects will be processed when the batch is submitted. Collections with collection sources (decomposition trees) are processed automatically via DAG resolution - no need to create separate batches.","examples":[["object_789","object_101"],["obj_video_001","obj_video_002","obj_video_003"]]}},"type":"object","required":["object_ids"],"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\n- object_ids: REQUIRED. List of object IDs that exist in the bucket\n- Collections are auto-discovered from the bucket at batch creation time\n\nBatch Processing Flow:\n1. Create batch with object_ids ā†’ Batch created in DRAFT status, collections auto-discovered\n2. Submit batch ā†’ 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 Single object batch:\n {\"object_ids\": [\"obj_123\"]}\n\n Multiple objects batch:\n {\"object_ids\": [\"obj_123\", \"obj_456\", \"obj_789\"]}"},"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āš ļø 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 ā†’ {upload_id, presigned_url} 2. User uploads file to presigned_url 3. POST /uploads/{upload_id}/confirm ā†’ 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":"Metadata for the blob, this will only be applied to the documents that use this blob"},"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āš ļø 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 ā†’ Returns presigned_url + upload_id\n - User uploads file directly to S3 via presigned_url\n - Then: POST /uploads/{upload_id}/confirm ā†’ 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 ā†’ 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"}]},"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."}},"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.0-flash","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.0-flash","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."},"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."}},"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_id":"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_id":"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."},"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 (alphanumeric with underscores, no 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)"}},"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 ā†’ Returns presigned_url + upload_id\n2. PUT presigned_url with model archive (client uploads directly to S3)\n3. POST /models/uploads/{upload_id}/confirm ā†’ 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_name":{"type":"string","title":"Namespace Name","description":"Name of the namespace to create","example":"spotify_playlists_dev"},"namespace_type":{"anyOf":[{"$ref":"#/components/schemas/NamespaceType"},{"type":"null"}],"description":"Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets.","default":"standard"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the namespace","example":"This namespace contains playlists from Spotify"},"feature_extractors":{"items":{"$ref":"#/components/schemas/BaseFeatureExtractorModel-Input"},"type":"array","minItems":1,"title":"Feature Extractors","description":"List of feature extractors to use. At least one feature extractor must be provided. 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_id":"multimodal_extractor_v1","feature_extractor_name":"multimodal_extractor","version":"v1"},{"feature_extractor_id":"image_extractor_v1","feature_extractor_name":"image_extractor","params":{"model":"siglip_base"},"version":"v1"}]},"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.","default":false,"example":true},"infrastructure":{"anyOf":[{"$ref":"#/components/schemas/NamespaceInfrastructure"},{"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","feature_extractors"],"title":"CreateNamespaceRequest","description":"Request schema for creating a new namespace."},"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"}]},"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 ā†’ Returns {upload_id, presigned_url}\n 2. User uploads file to presigned_url (client-side)\n 3. POST /uploads/{upload_id}/confirm ā†’ 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}]},"CreateOrganizationRequest":{"properties":{"organization_name":{"type":"string","maxLength":100,"minLength":1,"title":"Organization Name","description":"Display name for the organization."},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Organization logo URL (e.g., from Google Favicon service). If not provided, will be auto-generated from first user's email domain."},"users":{"anyOf":[{"items":{"$ref":"#/components/schemas/UserCreateRequest"},"type":"array"},{"type":"null"}],"title":"Users","description":"Initial users to create with the organization."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Custom metadata for the organization."},"credit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credit Count","description":"Initial credit count for the organization. Defaults to 1000 if not provided."},"account_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Type","description":"Account type for the organization (free, pro, team, enterprise). Defaults to 'free'."},"auth_provider_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Provider Org Id","description":"External auth provider org ID to associate with this organization."}},"type":"object","required":["organization_name"],"title":"CreateOrganizationRequest","description":"Payload for creating a new organization (private/admin endpoint).","examples":[{"logo_url":"https://www.google.com/s2/favicons?domain=acme.com&sz=128","metadata":{"region":"us-east-1"},"organization_name":"Acme Corp","users":[{"email":"admin@acme.com","role":"admin","user_name":"Admin User"}]}]},"CreatePageRequest":{"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)"},"template":{"type":"string","title":"Template","default":"generic"},"sections":{"items":{"$ref":"#/components/schemas/SectionConfig"},"type":"array","title":"Sections"},"custom_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Html"},"meta":{"$ref":"#/components/schemas/PageMeta"},"hero":{"anyOf":[{"$ref":"#/components/schemas/HeroConfig"},{"type":"null"}]},"theme":{"$ref":"#/components/schemas/ThemeConfig"},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}]},"stats":{"items":{"$ref":"#/components/schemas/StatItem"},"type":"array","title":"Stats"},"featured_gallery":{"anyOf":[{"$ref":"#/components/schemas/FeaturedGalleryConfig-Input"},{"type":"null"}]},"tabs":{"items":{"$ref":"#/components/schemas/PageTab-Input"},"type":"array","title":"Tabs"},"password_secret_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password Secret Name"},"is_active":{"type":"boolean","title":"Is Active","default":true}},"type":"object","required":["slug","meta"],"title":"CreatePageRequest","description":"Request to create a new Page."},"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).","examples":[["my_collection","products"],["col_abc123","col_def456"],[]]},"stages":{"items":{"$ref":"#/components/schemas/StageConfig"},"type":"array","minItems":1,"title":"Stages","description":"Ordered stage configurations (REQUIRED)."},"input_schema":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Input"},"type":"object","title":"Input Schema","description":"Input schema properties keyed by field name (OPTIONAL). Can be empty for static retrievers with hardcoded stage parameters. Each field can include: type, description, required, default, and examples. The 'examples' field (list) provides sample values that will be shown to users when the retriever is published with include_metadata=true.","examples":[{"category":{"description":"Filter by category","examples":["electronics","clothing"],"required":false,"type":"string"},"query":{"description":"Search query text","examples":["red sports car","sunset over ocean"],"required":true,"type":"text"}}]},"budget_limits":{"$ref":"#/components/schemas/BudgetLimits","description":"Budget limits for execution (OPTIONAL)."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Optional retriever tags for search/filters."},"display_config":{"anyOf":[{"$ref":"#/components/schemas/DisplayConfig-Input"},{"type":"null"}],"description":"Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever."}},"type":"object","required":["retriever_name","stages"],"title":"CreateRetrieverRequest","description":"Payload for creating a new retriever."},"CreateRetrieverResponse":{"properties":{"retriever":{"$ref":"#/components/schemas/RetrieverConfig","description":"Created retriever configuration."}},"type":"object","required":["retriever"],"title":"CreateRetrieverResponse","description":"Response after creating a retriever."},"CreateSecretRequest":{"properties":{"secret_name":{"type":"string","maxLength":100,"minLength":1,"title":"Secret Name","description":"REQUIRED. Name/key for the secret. Use descriptive names that indicate the service and purpose. Must be unique within the organization. Format: lowercase with underscores (e.g., 'stripe_api_key'). Common patterns: '{service}_{type}_{environment}' like 'stripe_api_key_prod'. This name is used to reference the secret in api_call stage configuration. Examples: 'stripe_api_key', 'github_token', 'openai_api_key', 'weather_api_key'.","examples":["stripe_api_key","github_token","openai_api_key","weather_api_key"]},"secret_value":{"type":"string","minLength":1,"title":"Secret Value","description":"REQUIRED. Plaintext secret value to encrypt and store. This value will be encrypted at rest using Fernet encryption. The encrypted value is stored in MongoDB with the organization document. The plaintext value is NEVER logged or exposed in API responses. Only the secret name is visible when listing secrets. Use this field to store: API keys, tokens, passwords, credentials. Format: any string (will be encrypted as-is). For Basic auth, use format 'username:password'.","examples":["sk_test_abc123...","ghp_abc123...","abc123def456"]}},"type":"object","required":["secret_name","secret_value"],"title":"CreateSecretRequest","description":"Request to create a new secret in the organization vault.\n\nSecrets are encrypted at rest using Fernet encryption and stored in the\norganization document. Use secrets to securely store API keys, tokens,\nand credentials for external services.\n\n**Use Cases**:\n- Store API keys for Stripe, GitHub, OpenAI, etc.\n- Manage authentication tokens for api_call retriever stage\n- Store credentials for third-party integrations\n\n**Security**:\n- Secret values are encrypted using ENCRYPTION_KEY from environment\n- Decrypted values are NEVER returned in API responses\n- Only secret names are exposed in list operations\n- Access is logged for audit trail\n\n**Requirements**:\n- secret_name: REQUIRED, must be unique within organization\n- secret_value: REQUIRED, plaintext value to encrypt\n\n**Permissions**: Requires ADMIN permission to create secrets.","examples":[{"description":"Store Stripe API key for payment processing","secret_name":"stripe_api_key","secret_value":"YOUR_STRIPE_API_KEY"},{"description":"Store GitHub Personal Access Token","secret_name":"github_pat","secret_value":"ghp_abc123def456ghi789jkl012mno345"},{"description":"Store OpenAI API key for LLM calls","secret_name":"openai_api_key","secret_value":"sk-proj-abc123def456ghi789"},{"description":"Store Weather API key","secret_name":"weather_api_key","secret_value":"abc123def456ghi789"}]},"CreateSessionRequest":{"properties":{"agent_config":{"$ref":"#/components/schemas/AgentConfig","description":"Agent configuration (REQUIRED)"},"quotas":{"anyOf":[{"$ref":"#/components/schemas/SessionQuotas"},{"type":"null"}],"description":"Session quotas and rate limits (OPTIONAL)"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User identifier (OPTIONAL)"},"user_memory":{"additionalProperties":true,"type":"object","title":"User Memory","description":"Initial user memory/preferences (OPTIONAL)"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Session metadata (OPTIONAL)"},"enable_memory":{"type":"boolean","title":"Enable Memory","description":"Enable semantic memory for conversation context (OPTIONAL, default: True)","default":true}},"type":"object","required":["agent_config"],"title":"CreateSessionRequest","description":"Request payload for creating a new agent session.\n\nAttributes:\n agent_config: Agent configuration (model, temperature, tools, etc.)\n quotas: Optional session quotas and rate limits\n user_id: Optional user identifier\n user_memory: Optional initial user memory/preferences\n metadata: Optional session metadata\n\nExample:\n ```python\n request = CreateSessionRequest(\n agent_config=AgentConfig(\n model=\"claude-3-5-sonnet-20241022\",\n temperature=0.7,\n available_tools=[\"search_retrievers\", \"execute_retriever\"]\n ),\n quotas=SessionQuotas(\n max_messages=100,\n max_tokens_total=100000\n ),\n user_id=\"user_123\",\n user_memory={\"preferences\": {\"language\": \"en\"}}\n )\n ```","examples":[{"agent_config":{"available_tools":["search_retrievers","execute_retriever","list_collections"],"max_tokens":4096,"model":"claude-3-5-sonnet-20241022","system_prompt":"You are a helpful video search assistant.","temperature":0.7},"quotas":{"max_messages":100,"max_tokens_total":100000,"max_tool_calls":50},"user_id":"user_123","user_memory":{"preferences":{"domain":"tech","language":"en"}}}]},"CreateSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Unique session identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace identifier"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal ID"},"session_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Name","description":"Auto-generated session name based on first conversation (set after first message)"},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Session status"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Session creation timestamp"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Session expiration timestamp"}},"type":"object","required":["session_id","namespace_id","internal_id","status","created_at","expires_at"],"title":"CreateSessionResponse","description":"Response for session creation.\n\nAttributes:\n session_id: Unique session identifier\n namespace_id: Namespace identifier\n internal_id: Organization internal ID\n session_name: Auto-generated session name (null until first message)\n status: Session status\n created_at: Session creation timestamp\n expires_at: Session expiration timestamp\n\nExample:\n ```python\n response = CreateSessionResponse(\n session_id=\"ses_abc123\",\n namespace_id=\"ns_xyz789\",\n internal_id=\"int_abc123\",\n session_name=None, # Will be set after first message\n status=\"active\",\n created_at=datetime.utcnow(),\n expires_at=datetime.utcnow() + timedelta(days=7)\n )\n ```"},"CreateTaxonomyRequest":{"properties":{"taxonomy_name":{"type":"string","title":"Taxonomy Name","description":"A unique name for the taxonomy within the namespace."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"An optional description of the taxonomy."},"config":{"oneOf":[{"$ref":"#/components/schemas/FlatTaxonomyConfig-Input"},{"$ref":"#/components/schemas/HierarchicalTaxonomyConfig-Input"}],"title":"Config","description":"Configuration specific to the taxonomy type.","discriminator":{"propertyName":"taxonomy_type","mapping":{"flat":"#/components/schemas/FlatTaxonomyConfig-Input","hierarchical":"#/components/schemas/HierarchicalTaxonomyConfig-Input"}}}},"type":"object","required":["taxonomy_name","config"],"title":"CreateTaxonomyRequest","description":"Request model to create a taxonomy.","examples":[{"config":{"collection_id":"col_products_v1","enrichment_fields":[{"field_path":"metadata.tags","merge_mode":"append"}],"input_mappings":[{"input_key":"image_vector","path":"features.clip","source_type":"vector"}],"retriever_id":"ret_clip_v1","taxonomy_type":"flat"},"taxonomy_name":"product_tags"},{"config":{"hierarchy":{"col_executives_v1":"col_employees_v1"},"input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"retriever_id":"ret_face_v1","taxonomy_type":"hierarchical"},"taxonomy_name":"org_hierarchy"}]},"CreateTemplateFromResourceRequest":{"properties":{"template_name":{"type":"string","maxLength":100,"minLength":1,"title":"Template Name","description":"Name for the new template"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description of the template's purpose (OPTIONAL)"},"scope":{"$ref":"#/components/schemas/TemplateScope","description":"Template scope: 'organization' (all users in org), 'user' (only you), or 'system' (all organizations - requires Mixpeek admin email)","default":"organization"},"category":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Category","description":"Optional category for organizing templates"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Optional tags for the template"},"is_public":{"type":"boolean","title":"Is Public","description":"Whether this template should be publicly discoverable","default":false}},"type":"object","required":["template_name"],"title":"CreateTemplateFromResourceRequest","description":"Request to create a template from an existing resource.","examples":[{"category":"ecommerce","description":"Semantic search optimized for product catalogs","is_public":false,"tags":["products","search"],"template_name":"My Product Search Pattern"}]},"CreateTemplateFromResourceResponse":{"properties":{"template_id":{"type":"string","title":"Template Id","description":"ID of the created template"},"template_name":{"type":"string","title":"Template Name","description":"Name of the created template"},"template_type":{"$ref":"#/components/schemas/TemplateType","description":"Type of template created"},"scope":{"$ref":"#/components/schemas/TemplateScope","description":"Template scope"},"source_resource_id":{"type":"string","title":"Source Resource Id","description":"ID of the resource used to create this template"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when template was created"}},"type":"object","required":["template_id","template_name","template_type","scope","source_resource_id"],"title":"CreateTemplateFromResourceResponse","description":"Response after creating a template from a resource.","examples":[{"created_at":"2025-01-15T12:00:00Z","scope":"organization","source_resource_id":"ret_xyz789","template_id":"tmpl_custom_abc123","template_name":"My Product Search Pattern","template_type":"retriever"}]},"CreateUploadRequest":{"properties":{"filename":{"type":"string","maxLength":255,"minLength":1,"title":"Filename","description":"Name of the file to upload. REQUIRED. Must be a valid filename without path traversal characters (../, \\). The filename is used to derive the blob_property if not explicitly provided. Examples: 'product_video.mp4', 'thumbnail.jpg', 'transcript.txt'","examples":["product_video.mp4","thumbnail.jpg","document.pdf"]},"content_type":{"type":"string","title":"Content Type","description":"MIME type of the file. REQUIRED. Must be a valid MIME type (e.g., 'video/mp4', 'image/jpeg', 'application/pdf'). The presigned URL will enforce this content type during upload. Used to validate compatibility with bucket schema if create_object_on_confirm=true.","examples":["video/mp4","image/jpeg","image/png","application/pdf","text/plain"]},"file_size_bytes":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"File Size Bytes","description":"Expected file size in bytes. OPTIONAL but RECOMMENDED. If provided, will be validated against: 1. Tier-based file size limits (100MB free, 5GB pro, 50GB enterprise) 2. Storage quota availability 3. Actual uploaded file size during confirmation. If not provided, quota checking is skipped until confirmation.","examples":[10485760,104857600]},"presigned_url_expiration":{"type":"integer","maximum":86400.0,"minimum":60.0,"title":"Presigned Url Expiration","description":"How long the presigned URL is valid, in seconds. OPTIONAL, defaults to 3600 (1 hour). Valid range: 60 seconds (1 minute) to 86400 seconds (24 hours). After expiration, the URL cannot be used and you must request a new one. Recommendation: Use shorter expiration (300-900 seconds) for security-sensitive files, longer expiration (3600-7200 seconds) for large files that take time to upload.","default":3600,"examples":[3600,7200,900]},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Custom metadata for tracking purposes. OPTIONAL. Stored with the upload record for filtering and analytics. Does NOT affect the created bucket object (use object_metadata for that). Common uses: campaign tracking, user identification, upload source.","examples":[{"campaign":"summer_2024","source":"mobile_app","user_id":"user_123"},{"department":"marketing","priority":"high"}]},"create_object_on_confirm":{"type":"boolean","title":"Create Object On Confirm","description":"Whether to automatically create a bucket object when upload is confirmed. OPTIONAL, defaults to TRUE (object is created automatically). If true (default): - Bucket MUST have a schema defined - blob_property must exist in bucket schema - content_type must match schema field type - Validation happens BEFORE generating presigned URL - Object is created automatically on confirmation. If false: - Upload is confirmed but no object is created - Use this when combining multiple uploads into one object - Reference the upload_id later in POST /buckets/{id}/objects.","default":true},"object_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Object Metadata","description":"Metadata to attach to the created bucket object. OPTIONAL. Only used if create_object_on_confirm=true. This metadata will be: 1. Validated against bucket schema (if keys match schema fields) 2. Attached to the bucket object 3. Passed to downstream documents in connected collections. Example: {'priority': 'high', 'category': 'products', 'tags': ['featured']}","examples":[{"category":"products","priority":"high"},{"campaign":"q4_2024","status":"draft","tags":["review","featured"]}]},"blob_property":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9_]+$"},{"type":"null"}],"title":"Blob Property","description":"Property name for the blob in the bucket object. OPTIONAL. Defaults to filename without extension (e.g., 'product_video.mp4' ā†’ 'product_video'). If create_object_on_confirm=true: - Must exist in bucket schema - Must be alphanumeric with underscores only - Will be validated BEFORE generating presigned URL. Common values: 'video', 'image', 'thumbnail', 'transcript', 'content'.","examples":["video","thumbnail","transcript","content"]},"blob_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blob Type","description":"Type of blob. OPTIONAL. Defaults to type derived from content_type (e.g., 'video/mp4' ā†’ 'VIDEO'). Must be a valid BucketSchemaFieldType if provided. Valid values: IMAGE, VIDEO, AUDIO, TEXT, PDF, DOCUMENT, etc. If create_object_on_confirm=true, will be validated against bucket schema field type.","examples":["VIDEO","IMAGE","AUDIO","TEXT","PDF"]},"file_hash":{"anyOf":[{"type":"string","maxLength":64,"minLength":64,"pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"File Hash","description":"SHA256 hash of the file content for duplicate detection. OPTIONAL. If provided: - System checks for existing confirmed uploads with same hash - If duplicate found and skip_duplicates=true, returns existing upload - Hash will be validated against actual S3 ETag during confirmation. If not provided: - Hash is calculated from S3 ETag after upload - Duplicate detection only happens during confirmation. Use case: Pre-calculate hash client-side to avoid uploading duplicates. Format: 64-character hexadecimal string (SHA256).","examples":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"]},"skip_duplicates":{"type":"boolean","title":"Skip Duplicates","description":"Skip upload if a file with the same hash already exists. OPTIONAL, defaults to TRUE. If true (default): - If file_hash provided: System checks MongoDB for existing completed upload with same hash - If duplicate found: Returns existing upload details WITHOUT generating new presigned URL - If file_hash NOT provided: Duplicate check happens during confirmation using S3 ETag - Saves bandwidth, storage, and upload time by reusing existing files. If false: - Always generates new presigned URL even if file already uploaded - Creates separate upload record for same file content - Useful when you need distinct upload tracking for identical files. Recommendation: Keep default (true) unless you specifically need multiple upload records for same file.","default":true}},"type":"object","required":["filename","content_type"],"title":"CreateUploadRequest","description":"Request to generate a presigned URL for direct S3 upload.\n\nāš ļø āš ļø āš ļø THIS IS THE PRESIGNED URL SYSTEM āš ļø āš ļø āš ļø\n\nThis endpoint (POST /buckets/{id}/uploads) is the COMPLETE presigned URL system.\nIt handles:\n- āœ… Presigned URL generation (S3 PUT URLs)\n- āœ… Upload tracking and status management\n- āœ… Validation (quotas, file size, content type, schema)\n- āœ… Duplicate detection\n- āœ… Auto object creation on confirmation\n- āœ… Returns upload_id for later reference\n\nDO NOT CREATE A NEW PRESIGNED UPLOAD ENDPOINT!\nIf you need presigned URLs, use this existing system.\n\nIf you think you need a new endpoint:\n1. Check if this system already does it (it probably does)\n2. Extend this system instead of creating redundancy\n3. See api/buckets/uploads/services.py for implementation\n\nIntegration Points:\n- Object creation: Use upload_id in CreateBlobRequest.upload_id field\n- See: shared/buckets/objects/blobs/models.py::CreateBlobRequest\n- See: api/buckets/objects/canonicalization.py::resolve_upload_reference()\n\nWorkflow:\n1. POST /buckets/{id}/uploads ā†’ Returns presigned_url + upload_id\n2. PUT presigned_url with file content (client uploads directly to S3)\n3. POST /uploads/{upload_id}/confirm ā†’ REQUIRED to finalize upload\n4. Object is created automatically (default behavior)\n\nāš ļø IMPORTANT: Step 3 (confirm) is REQUIRED!\nS3 presigned URLs have no callback mechanism - the API cannot detect when\nyour upload to S3 completes. You MUST call the confirm endpoint to:\n- Verify the file exists in S3\n- Validate integrity (ETag/size)\n- Create the bucket object\n- Mark upload as COMPLETED\n\nIf you don't confirm:\n- Upload stays in PENDING status forever\n- No object is created\n- File exists in S3 but is orphaned\n- Presigned URL expires (default: 1 hour)\n\nUse Cases:\n - Simple: Upload ā†’ confirm ā†’ object created automatically (default)\n - Advanced: Upload multiple files with create_object_on_confirm=false,\n then POST /buckets/{id}/objects with all upload_ids to create one object\n\nRequirements:\n - filename: REQUIRED, will be validated (no path traversal)\n - content_type: REQUIRED, must be valid MIME type\n - bucket_id: Comes from URL path parameter, not request body\n - All other fields: OPTIONAL with sensible defaults\n\nNote:\n The bucket_id comes from the URL path (/v1/buckets/{bucket_id}/uploads),\n not from the request body. The bucket is validated before generating presigned URL.","examples":[{"content_type":"video/mp4","description":"Minimal upload - object created automatically on confirm (DEFAULT)","file_size_bytes":52428800,"filename":"product_demo.mp4"},{"blob_property":"image","content_type":"image/jpeg","description":"Upload with metadata - object still created automatically","file_size_bytes":2097152,"filename":"profile.jpg","object_metadata":{"category":"avatars","title":"Profile Image"}},{"blob_property":"raw_video","content_type":"video/quicktime","description":"Large file with extended expiration","file_size_bytes":5368709120,"filename":"4k_footage.mov","presigned_url_expiration":7200},{"content_type":"video/mp4","create_object_on_confirm":false,"description":"ADVANCED: Manual object creation - set create_object_on_confirm=false","file_size_bytes":104857600,"filename":"video.mp4","note":"Only use this when combining multiple uploads into one object","use_case":"Combine multiple uploads into one object","workflow":["1. POST /uploads (video) with create_object_on_confirm=false","2. POST /uploads (thumbnail) with create_object_on_confirm=false","3. Upload both files to S3","4. Confirm both uploads","5. POST /buckets/{id}/objects with both upload_ids:"," {blobs: [{property: 'video', upload_id: 'upl_video'}, {property: 'thumb', upload_id: 'upl_thumb'}]}"]}]},"CreatorInfo":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User identifier"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"User email address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"User display name"}},"type":"object","required":["user_id"],"title":"CreatorInfo","description":"Information about who created or updated a resource."},"CreditBalanceResponse":{"properties":{"organization_id":{"type":"string","title":"Organization Id","description":"Organization identifier","examples":["org_demo123"]},"credit_balance":{"type":"integer","title":"Credit Balance","description":"Current credit balance. For FREE tier without auto-billing, this is remaining free tier credits. For auto-billing accounts, this shows current month usage (negative indicates consumption).","examples":[45230,750]},"account_tier":{"type":"string","title":"Account Tier","description":"Current account tier: free, pro, team, enterprise","examples":["free","pro","team"]},"next_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Tier","description":"Next available tier or null if at max tier","examples":["pro","team","enterprise"]},"credits_until_next_tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Until Next Tier","description":"Credits needed to reach next tier (null if at max tier or N/A)","examples":[954770,0]},"estimated_days_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Days Remaining","description":"Estimated days until credits depleted based on 7-day burn rate. Null if no usage history or unlimited (auto-billing enabled).","examples":[15,30]},"daily_burn_rate":{"type":"number","title":"Daily Burn Rate","description":"Average credits consumed per day (7-day rolling average)","default":0.0,"examples":[3015.3,142.5]}},"type":"object","required":["organization_id","credit_balance","account_tier"],"title":"CreditBalanceResponse","description":"Response with current credit balance and tier information."},"CurrentUsageResponse":{"properties":{"current_month_usage":{"type":"integer","title":"Current Month Usage","description":"Credits consumed in current billing cycle","examples":[23450]},"billing_month":{"type":"string","title":"Billing Month","description":"Current billing month (YYYY-MM)","examples":["2025-12"]},"billing_period_start":{"type":"string","format":"date-time","title":"Billing Period Start","description":"Start of current billing period"},"billing_period_end":{"type":"string","format":"date-time","title":"Billing Period End","description":"End of current billing period"},"estimated_cost_usd":{"type":"number","title":"Estimated Cost Usd","description":"Estimated cost for current usage","examples":[23.45]},"credit_rate":{"type":"number","title":"Credit Rate","description":"Cost per credit in USD","default":0.001},"auto_billing_enabled":{"type":"boolean","title":"Auto Billing Enabled","description":"Whether auto-billing is enabled"},"next_invoice_date":{"type":"string","format":"date-time","title":"Next Invoice Date","description":"When next invoice will be generated"}},"type":"object","required":["current_month_usage","billing_month","billing_period_start","billing_period_end","estimated_cost_usd","auto_billing_enabled","next_invoice_date"],"title":"CurrentUsageResponse","description":"Response with current month usage."},"CursorPaginationParams":{"properties":{"method":{"$ref":"#/components/schemas/PaginationMethod","description":"Constant identifying cursor pagination (REQUIRED).","default":"cursor"},"limit":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","description":"Maximum number of documents to return per page (REQUIRED). Default: 10.","default":10},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Opaque base64 cursor from previous response (OPTIONAL). null for first page, then use cursor from response.pagination.cursor"}},"type":"object","title":"CursorPaginationParams","description":"Cursor-based pagination referencing last seen position.\n\nBest for: Infinite scroll UIs, mobile apps, real-time feeds\n\nHow it works:\n- First request: cursor=null\n- Response includes next cursor token\n- Next request: pass cursor from previous response\n- Stateless: no server-side state\n- Consistent: no duplicates/gaps even with concurrent writes\n\nUse when:\n- Building infinite scroll interfaces\n- Users scroll through results sequentially\n- You need consistency across pages\n- You don't need to jump to arbitrary pages\n\nExample flow:\n1. Request: {\"method\": \"cursor\", \"limit\": 20, \"cursor\": null}\n2. Response: {\"documents\": [...], \"pagination\": {\"cursor\": \"abc123\", \"has_next\": true}}\n3. Request: {\"method\": \"cursor\", \"limit\": 20, \"cursor\": \"abc123\"}"},"CustomCTA":{"properties":{"label":{"type":"string","maxLength":50,"minLength":1,"title":"Label","description":"Button label text displayed in the header","examples":["How to Use","Search Tips","About","Help"]},"markdown_content":{"type":"string","maxLength":50000,"minLength":1,"title":"Markdown Content","description":"Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax.","examples":["# Getting Started\n\nThis search engine allows you to...\n\n## Tips\n\n- Use specific keywords\n- Try different queries"]}},"type":"object","required":["label","markdown_content"],"title":"CustomCTA","description":"Optional custom button in header that opens a markdown modal.\n\nAllows users to add a custom call-to-action button in the header bar\nthat opens a modal with markdown content when clicked.","examples":[{"label":"Search Tips","markdown_content":"# Search Tips\n\n- Use quotes for exact phrases\n- Filter by date using 'after:2024'"}]},"CustomModelDocument":{"properties":{"model_id":{"type":"string","title":"Model Id","description":"Unique model identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Owner namespace ID"},"name":{"type":"string","title":"Name","description":"Model name"},"version":{"type":"string","title":"Version","description":"Model version"},"model_archive_url":{"type":"string","title":"Model Archive Url","description":"S3 URL to model archive"},"model_format":{"type":"string","enum":["safetensors","onnx","pytorch","huggingface"],"title":"Model Format","description":"Model format/framework"},"model_hash":{"type":"string","title":"Model Hash","description":"SHA256 hash of model file"},"deployed":{"type":"boolean","title":"Deployed","description":"Whether model is deployed","default":false},"deployment_info":{"anyOf":[{"$ref":"#/components/schemas/ModelDeploymentInfo"},{"type":"null"}],"description":"Deployment details"},"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)"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"Input schema JSON"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"Output schema JSON"},"resource_requirements":{"$ref":"#/components/schemas/ModelResourceRequirements","description":"Resource requirements for deployment"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"}},"type":"object","required":["model_id","namespace_id","name","version","model_archive_url","model_format","model_hash"],"title":"CustomModelDocument","description":"Custom model document stored in MongoDB."},"CustomPluginParams":{"properties":{"extractor_type":{"type":"string","title":"Extractor Type","description":"Custom plugin extractor type (plugin name)"}},"additionalProperties":true,"type":"object","required":["extractor_type"],"title":"CustomPluginParams","description":"Parameters for custom plugin extractors.\n\nThis model accepts any extractor_type that doesn't match the builtin extractors,\nallowing custom plugins to define their own parameters."},"DBSCANParams":{"properties":{"eps":{"type":"number","exclusiveMinimum":0.0,"title":"Eps","description":"Maximum distance between two samples for one to be considered in the neighborhood of the other","default":0.5},"min_samples":{"type":"integer","minimum":1.0,"title":"Min Samples","description":"Number of samples in a neighborhood for a point to be considered a core point","default":5},"metric":{"type":"string","title":"Metric","description":"Metric to use for distance computation","default":"euclidean"},"metric_params":{"additionalProperties":true,"type":"object","title":"Metric Params","description":"Additional keyword arguments for the metric function"},"algorithm":{"type":"string","title":"Algorithm","description":"Algorithm to compute pointwise distances and find nearest neighbors ('auto', 'ball_tree', 'kd_tree', 'brute')","default":"auto"},"leaf_size":{"type":"integer","minimum":1.0,"title":"Leaf Size","description":"Leaf size passed to BallTree or KDTree","default":30},"p":{"type":"number","exclusiveMinimum":0.0,"title":"P","description":"The power of the Minkowski metric to be used to calculate distance between points","default":2},"n_jobs":{"type":"integer","title":"N Jobs","description":"The number of parallel jobs to run (-1 means using all processors)","default":1}},"type":"object","title":"DBSCANParams","description":"Parameters for DBSCAN clustering algorithm."},"DatasetListResponse":{"properties":{"datasets":{"items":{"$ref":"#/components/schemas/EvaluationDataset"},"type":"array","title":"Datasets","description":"List of datasets"},"total":{"type":"integer","title":"Total","description":"Total number of datasets"},"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Items per page"}},"type":"object","required":["datasets","total","page","page_size"],"title":"DatasetListResponse","description":"Response model for listing datasets."},"DatePartUnit":{"type":"string","enum":["year","month","week","day","dayOfWeek","dayOfYear","hour","minute","second"],"title":"DatePartUnit","description":"Date part extraction units.\n\nUsed to extract specific components from dates for grouping.\n\nValues:\n YEAR: Extract year (2024)\n MONTH: Extract month (1-12)\n WEEK: Extract week of year (1-53)\n DAY: Extract day of month (1-31)\n DAY_OF_WEEK: Extract day of week (1=Sunday, 7=Saturday)\n DAY_OF_YEAR: Extract day of year (1-366)\n HOUR: Extract hour (0-23)\n MINUTE: Extract minute (0-59)\n SECOND: Extract second (0-59)\n\nExamples:\n - Use DAY_OF_WEEK to analyze weekly patterns\n - Use HOUR to find peak usage times"},"DateTruncUnit":{"type":"string","enum":["year","month","week","day","hour","minute","second"],"title":"DateTruncUnit","description":"Date truncation units for time-based grouping.\n\nUsed to group data by time periods.\n\nValues:\n YEAR: Group by year\n MONTH: Group by month\n WEEK: Group by week\n DAY: Group by day\n HOUR: Group by hour\n MINUTE: Group by minute\n SECOND: Group by second\n\nExamples:\n - Use DAY to group video uploads by day\n - Use MONTH to analyze monthly trends"},"DatetimeIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"datetime"}},"type":"object","title":"DatetimeIndexParams","description":"Configuration for datetime index."},"DenseVector":{"properties":{},"additionalProperties":true,"type":"object","title":"DenseVector","description":"Basic dense vector representation with flexible key naming.\n\nAccepts a single key-value pair where the key can be any string\nand the value must be a list of floats.\n\nExample:\n```json\n{\n \"embedding\": [0.1, 0.2, 0.3, 0.4, 0.5]\n}\n```\nor\n```json\n{\n \"my_custom_vector\": [0.1, 0.2, 0.3, 0.4, 0.5]\n}\n```"},"DependencyGraph":{"properties":{"nodes":{"items":{"$ref":"#/components/schemas/DependencyNode"},"type":"array","title":"Nodes","description":"All resource nodes"},"execution_order":{"items":{"type":"string"},"type":"array","title":"Execution Order","description":"Topologically sorted execution order"}},"type":"object","title":"DependencyGraph","description":"Dependency graph for migration ordering."},"DependencyNode":{"properties":{"resource_id":{"type":"string","title":"Resource Id","description":"Resource ID"},"resource_type":{"$ref":"#/components/schemas/shared__namespaces__migrations__models__ResourceType","description":"Resource type"},"dependencies":{"items":{"type":"string"},"type":"array","title":"Dependencies","description":"IDs of resources this depends on"},"tier":{"type":"integer","minimum":0.0,"title":"Tier","description":"Dependency tier (0=no deps)","default":0}},"type":"object","required":["resource_id","resource_type"],"title":"DependencyNode","description":"Node in dependency graph."},"DescribeCollectionFeaturesResponse":{"properties":{"features":{"items":{"$ref":"#/components/schemas/CollectionFeatureDescriptor"},"type":"array","title":"Features","description":"Feature extractors and fields enabled on this collection"}},"type":"object","required":["features"],"title":"DescribeCollectionFeaturesResponse","examples":[{"features":[{"feature_extractor_name":"text_extractor","inputs":[{"path":"text","type":"string"}],"outputs":[{"dim":1024,"path":"features.text_embedding","type":"vector"}],"version":"v1"}]}]},"DetectIntentRequest":{"properties":{"user_request":{"type":"string","title":"User Request","description":"User's natural language request"},"include_collection_analysis":{"type":"boolean","title":"Include Collection Analysis","description":"Whether to check existing collections","default":true}},"type":"object","required":["user_request"],"title":"DetectIntentRequest","description":"Request to detect intent from user input.\n\nAttributes:\n user_request: The user's natural language request to analyze\n include_collection_analysis: Whether to analyze existing collections"},"DiffItem":{"properties":{"resource_type":{"type":"string","title":"Resource Type","description":"Type of resource"},"name":{"type":"string","title":"Name","description":"Resource name"},"action":{"type":"string","title":"Action","description":"Action: create, update, delete, unchanged"},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Details","description":"Details about the difference"}},"type":"object","required":["resource_type","name","action"],"title":"DiffItem","description":"A single difference between manifest and current state."},"DiffResult":{"properties":{"to_create":{"items":{"$ref":"#/components/schemas/DiffItem"},"type":"array","title":"To Create","description":"Resources in manifest but not in system"},"in_system_only":{"items":{"$ref":"#/components/schemas/DiffItem"},"type":"array","title":"In System Only","description":"Resources in system but not in manifest"},"differences":{"items":{"$ref":"#/components/schemas/DiffItem"},"type":"array","title":"Differences","description":"Resources in both with differences"}},"type":"object","title":"DiffResult","description":"Result of comparing manifest to current state."},"DisableOrgModelResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether operation succeeded"},"model_id":{"type":"string","title":"Model Id","description":"Model identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace where model was disabled"},"message":{"type":"string","title":"Message","description":"Status message"}},"type":"object","required":["success","model_id","namespace_id","message"],"title":"DisableOrgModelResponse","description":"Response from disabling an org-level model for a namespace."},"DisableOrgPluginResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the operation succeeded"},"plugin_id":{"type":"string","title":"Plugin Id","description":"The plugin ID that was disabled"},"namespace_id":{"type":"string","title":"Namespace Id","description":"The namespace where plugin was disabled"},"message":{"type":"string","title":"Message","description":"Status message"}},"type":"object","required":["success","plugin_id","namespace_id","message"],"title":"DisableOrgPluginResponse","description":"Response from disabling an org-level plugin for a namespace."},"DiscoveryResponse":{"properties":{"extractors":{"items":{"$ref":"#/components/schemas/ExtractorDiscovery"},"type":"array","title":"Extractors","description":"Available feature extractors"},"stages":{"items":{"$ref":"#/components/schemas/StageDiscovery"},"type":"array","title":"Stages","description":"Available retriever stages"},"manifest_schema":{"anyOf":[{"$ref":"#/components/schemas/ManifestSchemaDiscovery"},{"type":"null"}],"description":"Manifest schema information"}},"type":"object","title":"DiscoveryResponse","description":"Combined discovery response with all available resources."},"DisplayConfig-Input":{"properties":{"title":{"type":"string","title":"Title","description":"Title/heading for the public search page","examples":["Product Search","Video Library","Creative Assets"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description/subtitle for the page","examples":["Search through thousands of products","Find the perfect video clip"]},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"URL to logo image","examples":["https://example.com/logo.png"]},"icon_base64":{"anyOf":[{"type":"string","maxLength":300000},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...'","examples":["data:image/png;base64,iVBORw0KGgoAAAANS..."]},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}],"description":"SEO configuration for search engine and social media discoverability. Auto-generated during publishing with sensible defaults inferred from title, description, and retriever metadata. All fields can be overridden."},"markdowns":{"items":{"$ref":"#/components/schemas/MarkdownContent"},"type":"array","title":"Markdowns","description":"Array of markdown content sections for documentation, guides, or informational modals. Each section has a title and markdown-formatted content. Displayed in modals, expandable sections, or tabs on the public interface. Examples: 'How it Works', 'Search Guide', 'About', 'FAQ', etc."},"theme":{"$ref":"#/components/schemas/ThemeConfig","description":"Theme/styling configuration"},"inputs":{"items":{"$ref":"#/components/schemas/InputRenderingConfig-Input"},"type":"array","title":"Inputs","description":"List of input fields to render in the search interface. Each input maps to a field in the retriever's input_schema. Frontend uses the field_schema to render the appropriate component type."},"layout":{"$ref":"#/components/schemas/LayoutConfig","description":"Layout configuration for results"},"exposed_fields":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Exposed Fields","description":"List of document metadata fields to show in results. Only these fields are returned to end users."},"components":{"$ref":"#/components/schemas/ComponentsConfig","description":"Configuration for UI components including search inputs, filters, and result card display options."},"field_config":{"additionalProperties":{"$ref":"#/components/schemas/FieldConfig"},"type":"object","title":"Field Config","description":"Configuration for how each field should be displayed. Keys are field names (must be subset of exposed_fields). Values are FieldConfig objects specifying format and display options.","examples":[{"created_at":{"format":"date","format_options":{"date_format":"relative","label":"Posted"}},"price":{"format":"number","format_options":{"decimals":2,"label":"Price","prefix":"$"}},"thumbnail_url":{"format":"image","format_options":{"aspect_ratio":"16/9","height":300,"width":400}},"title":{"format":"text","format_options":{"label":"Title","truncate_chars":60}}}]},"custom_cta":{"anyOf":[{"$ref":"#/components/schemas/CustomCTA"},{"type":"null"}],"description":"Optional custom call-to-action button displayed in the header bar. Opens a markdown modal when clicked."},"external_links":{"items":{"$ref":"#/components/schemas/ExternalLink"},"type":"array","title":"External Links","description":"External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.","examples":[[{"name":"GitHub Repository","url":"https://github.com/org/repo"},{"name":"Blog Post","url":"https://blog.example.com/post"}]]},"template_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Type","description":"Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.","examples":["portrait-gallery","media-search","document-search"]},"field_mappings":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Field Mappings","description":"Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results.","examples":[{"boundingBox":"ocr_bbox","extractedText":"ocr_text","thumbnail":"page_thumbnail_url","title":"document_title"}]},"extensions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Extensions","description":"Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.","examples":[{"show_timestamps":true,"video_autoplay":true},{"bbox_highlight_color":"#FF0000","show_confidence_badge":true}]},"retriever_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Retriever Config","description":"Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time."}},"additionalProperties":true,"type":"object","required":["title","inputs","exposed_fields"],"title":"DisplayConfig","description":"Display configuration for public retriever UI.\n\nThis model defines how the public search interface should be rendered,\nincluding input fields, theme, layout, and result card configuration.\n\nThe frontend (mxp.co) uses this to dynamically build the UI\nwithout hardcoded components.","examples":[{"components":{"result_card":{"card_click_action":"viewDetails","field_order":["title","description","price"],"layout":"vertical","show_find_similar":true,"show_thumbnail":true},"result_layout":"grid","show_hero":true,"show_results_header":true,"show_search":true},"custom_cta":{"label":"Search Tips","markdown_content":"# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"},"description":"Search through our product catalog","exposed_fields":["title","description","price","image_url"],"external_links":[{"name":"GitHub Repository","url":"https://github.com/mixpeek/product-search"},{"name":"Blog Post","url":"https://blog.mixpeek.com/building-product-search"}],"field_config":{"price":{"format":"number","format_options":{"decimals":2,"label":"Price","prefix":"$"}},"title":{"format":"text","format_options":{"label":"Product Name","truncate_chars":60}}},"field_mappings":{"thumbnail":"image_url","title":"title"},"inputs":[{"field_name":"query","field_schema":{"description":"Search query","examples":["wireless headphones","laptop"],"type":"string"},"input_type":"text","label":"Search Products","order":0,"placeholder":"What are you looking for?","required":true}],"layout":{"columns":3,"gap":"16px","mode":"grid"},"logo_url":"https://example.com/logo.png","markdowns":[{"content":"# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters","title":"How it Works"},{"content":"## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*","title":"Search Guide"}],"template_type":"media-search","theme":{"border_radius":"12px","card_style":"elevated","font_family":"Inter, sans-serif","primary_color":"#007AFF"},"title":"Product Search"}]},"DisplayConfig-Output":{"properties":{"title":{"type":"string","title":"Title","description":"Title/heading for the public search page","examples":["Product Search","Video Library","Creative Assets"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description/subtitle for the page","examples":["Search through thousands of products","Find the perfect video clip"]},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"URL to logo image","examples":["https://example.com/logo.png"]},"icon_base64":{"anyOf":[{"type":"string","maxLength":300000},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...'","examples":["data:image/png;base64,iVBORw0KGgoAAAANS..."]},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}],"description":"SEO configuration for search engine and social media discoverability. Auto-generated during publishing with sensible defaults inferred from title, description, and retriever metadata. All fields can be overridden."},"markdowns":{"items":{"$ref":"#/components/schemas/MarkdownContent"},"type":"array","title":"Markdowns","description":"Array of markdown content sections for documentation, guides, or informational modals. Each section has a title and markdown-formatted content. Displayed in modals, expandable sections, or tabs on the public interface. Examples: 'How it Works', 'Search Guide', 'About', 'FAQ', etc."},"theme":{"$ref":"#/components/schemas/ThemeConfig","description":"Theme/styling configuration"},"inputs":{"items":{"$ref":"#/components/schemas/InputRenderingConfig-Output"},"type":"array","title":"Inputs","description":"List of input fields to render in the search interface. Each input maps to a field in the retriever's input_schema. Frontend uses the field_schema to render the appropriate component type."},"layout":{"$ref":"#/components/schemas/LayoutConfig","description":"Layout configuration for results"},"exposed_fields":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Exposed Fields","description":"List of document metadata fields to show in results. Only these fields are returned to end users."},"components":{"$ref":"#/components/schemas/ComponentsConfig","description":"Configuration for UI components including search inputs, filters, and result card display options."},"field_config":{"additionalProperties":{"$ref":"#/components/schemas/FieldConfig"},"type":"object","title":"Field Config","description":"Configuration for how each field should be displayed. Keys are field names (must be subset of exposed_fields). Values are FieldConfig objects specifying format and display options.","examples":[{"created_at":{"format":"date","format_options":{"date_format":"relative","label":"Posted"}},"price":{"format":"number","format_options":{"decimals":2,"label":"Price","prefix":"$"}},"thumbnail_url":{"format":"image","format_options":{"aspect_ratio":"16/9","height":300,"width":400}},"title":{"format":"text","format_options":{"label":"Title","truncate_chars":60}}}]},"custom_cta":{"anyOf":[{"$ref":"#/components/schemas/CustomCTA"},{"type":"null"}],"description":"Optional custom call-to-action button displayed in the header bar. Opens a markdown modal when clicked."},"external_links":{"items":{"$ref":"#/components/schemas/ExternalLink"},"type":"array","title":"External Links","description":"External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.","examples":[[{"name":"GitHub Repository","url":"https://github.com/org/repo"},{"name":"Blog Post","url":"https://blog.example.com/post"}]]},"template_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Type","description":"Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.","examples":["portrait-gallery","media-search","document-search"]},"field_mappings":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Field Mappings","description":"Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results.","examples":[{"boundingBox":"ocr_bbox","extractedText":"ocr_text","thumbnail":"page_thumbnail_url","title":"document_title"}]},"extensions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Extensions","description":"Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.","examples":[{"show_timestamps":true,"video_autoplay":true},{"bbox_highlight_color":"#FF0000","show_confidence_badge":true}]},"retriever_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Retriever Config","description":"Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time."}},"additionalProperties":true,"type":"object","required":["title","inputs","exposed_fields"],"title":"DisplayConfig","description":"Display configuration for public retriever UI.\n\nThis model defines how the public search interface should be rendered,\nincluding input fields, theme, layout, and result card configuration.\n\nThe frontend (mxp.co) uses this to dynamically build the UI\nwithout hardcoded components.","examples":[{"components":{"result_card":{"card_click_action":"viewDetails","field_order":["title","description","price"],"layout":"vertical","show_find_similar":true,"show_thumbnail":true},"result_layout":"grid","show_hero":true,"show_results_header":true,"show_search":true},"custom_cta":{"label":"Search Tips","markdown_content":"# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"},"description":"Search through our product catalog","exposed_fields":["title","description","price","image_url"],"external_links":[{"name":"GitHub Repository","url":"https://github.com/mixpeek/product-search"},{"name":"Blog Post","url":"https://blog.mixpeek.com/building-product-search"}],"field_config":{"price":{"format":"number","format_options":{"decimals":2,"label":"Price","prefix":"$"}},"title":{"format":"text","format_options":{"label":"Product Name","truncate_chars":60}}},"field_mappings":{"thumbnail":"image_url","title":"title"},"inputs":[{"field_name":"query","field_schema":{"description":"Search query","examples":["wireless headphones","laptop"],"type":"string"},"input_type":"text","label":"Search Products","order":0,"placeholder":"What are you looking for?","required":true}],"layout":{"columns":3,"gap":"16px","mode":"grid"},"logo_url":"https://example.com/logo.png","markdowns":[{"content":"# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters","title":"How it Works"},{"content":"## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*","title":"Search Guide"}],"template_type":"media-search","theme":{"border_radius":"12px","card_style":"elevated","font_family":"Inter, sans-serif","primary_color":"#007AFF"},"title":"Product Search"}]},"DocsSearchOptions":{"properties":{"enable_image_search":{"type":"boolean","title":"Enable Image Search","description":"Enable SigLIP image embeddings for diagram/screenshot search.","default":false},"enable_code_search":{"type":"boolean","title":"Enable Code Search","description":"Enable Jina Code embeddings for code-aware search.","default":true},"max_pages":{"type":"integer","maximum":5000.0,"minimum":1.0,"title":"Max Pages","description":"Maximum pages to crawl.","default":200},"max_depth":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Depth","description":"Maximum crawl depth from seed URL.","default":3},"chunk_strategy":{"type":"string","title":"Chunk Strategy","description":"Text chunking strategy.","default":"paragraphs"},"chunk_size":{"type":"integer","maximum":2000.0,"minimum":100.0,"title":"Chunk Size","description":"Chunk size in units of chunk_strategy.","default":500},"render_strategy":{"type":"string","title":"Render Strategy","description":"Page rendering strategy: static, javascript, or auto.","default":"auto"}},"type":"object","title":"DocsSearchOptions","description":"Optional configuration for docs search setup."},"DocsSearchRequest":{"properties":{"site_url":{"type":"string","minLength":1,"title":"Site Url","description":"Root URL of the documentation site to crawl.","examples":["https://docs.example.com","https://example.com/docs"]},"site_name":{"type":"string","maxLength":100,"minLength":1,"title":"Site Name","description":"Human-readable name for the docs site.","examples":["Example Docs","Acme API Reference"]},"include_patterns":{"items":{"type":"string"},"type":"array","title":"Include Patterns","description":"URL patterns to include (regex). Empty means include all.","examples":[["/docs/.*","/api/.*"]]},"exclude_patterns":{"items":{"type":"string"},"type":"array","title":"Exclude Patterns","description":"URL patterns to exclude (regex).","examples":[["*/changelog/*","*/blog/*"]]},"namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Namespace Id","description":"Existing namespace ID. If not provided, one will be created."},"options":{"$ref":"#/components/schemas/DocsSearchOptions","description":"Optional configuration overrides."}},"type":"object","required":["site_url","site_name"],"title":"DocsSearchRequest","description":"Request to provision a docs search pipeline."},"DocsSearchResponse":{"properties":{"project_key":{"type":"string","title":"Project Key","description":"Retriever-scoped API key (ret_sk_...) for widget authentication."},"public_name":{"type":"string","title":"Public Name","description":"Public retriever name for API access."},"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the created retriever."},"collection_id":{"type":"string","title":"Collection Id","description":"ID of the web crawl collection."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"ID of the crawl batch (if processing started)."},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID for all resources."},"bucket_id":{"type":"string","title":"Bucket Id","description":"Bucket ID where seed URLs are stored."},"embed_snippet":{"type":"string","title":"Embed Snippet","description":"HTML snippet for drop-in integration."},"react_snippet":{"type":"string","title":"React Snippet","description":"React component snippet."}},"type":"object","required":["project_key","public_name","retriever_id","collection_id","namespace_id","bucket_id","embed_snippet","react_snippet"],"title":"DocsSearchResponse","description":"Response after provisioning a docs search pipeline."},"DocumentAggregationRequest":{"properties":{"group_by":{"items":{"$ref":"#/components/schemas/GroupByField"},"type":"array","minItems":1,"title":"Group By","description":"Fields to group results by. REQUIRED, at least one field. Can include field transformations (date_trunc, date_part). Results will have one row per unique combination of group_by values."},"aggregations":{"items":{"$ref":"#/components/schemas/AggregationOperation"},"type":"array","minItems":1,"title":"Aggregations","description":"Aggregation operations to perform. REQUIRED, at least one operation. Each operation produces a calculated field in results. Can combine multiple functions (COUNT, SUM, AVG, etc.)."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY.","examples":[{"metadata.status":"active"},{"created_at":{"$gte":"2024-01-01"},"metadata.type":"video"}]},"having":{"anyOf":[{"items":{"$ref":"#/components/schemas/HavingCondition"},"type":"array"},{"type":"null"}],"title":"Having","description":"Post-aggregation filters to apply to results. OPTIONAL, filters groups after aggregation. Uses aggregation aliases as field names. Applied after GROUP BY and aggregation calculations."},"unwind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unwind","description":"Array field to unwind before aggregation. OPTIONAL, creates one document per array element. Useful for aggregating over array contents. Example: 'blobs' to analyze each blob separately.","examples":["blobs","metadata.tags","metadata.categories"]},"range_buckets":{"anyOf":[{"items":{"$ref":"#/components/schemas/RangeBucket"},"type":"array"},{"type":"null"}],"title":"Range Buckets","description":"Range-based bucketing for numeric fields. OPTIONAL, creates histogram-style buckets. Groups numeric values into defined ranges. Applied during grouping stage."},"sort_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By","description":"Field to sort results by. OPTIONAL, can be group_by field or aggregation alias. Defaults to no specific order. Use with sort_direction to control order.","examples":["total_count","avg_duration","category"]},"sort_direction":{"type":"string","title":"Sort Direction","description":"Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field.","default":"desc","examples":["asc","desc"]},"limit":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Limit","description":"Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries.","examples":[10,50,100]}},"type":"object","required":["group_by","aggregations"],"title":"DocumentAggregationRequest","description":"Aggregation request for collection documents.\n\nExtends the base AggregationRequest with document-specific context.\nInherits all fields from AggregationRequest.\n\nRequirements:\n - group_by: REQUIRED, fields to group by\n - aggregations: REQUIRED, aggregation operations to perform\n - All other fields from AggregationRequest are available\n\nExamples:\n - Count documents by feature type\n - Daily processing statistics\n - User-based analytics with filtering","examples":[{"aggregations":[{"alias":"total","function":"count"}],"description":"Count documents by collection","group_by":[{"alias":"collection","field":"collection_id"}],"sort_by":"total","sort_direction":"desc"},{"aggregations":[{"alias":"documents","function":"count"},{"alias":"unique_objects","distinct_field":"object_id","function":"count_distinct"}],"description":"Daily document creation statistics","group_by":[{"alias":"date","date_trunc":"day","field":"created_at"}],"sort_by":"date","sort_direction":"asc"},{"aggregations":[{"alias":"count","function":"count"},{"alias":"avg_confidence","field":"features.confidence","function":"avg"}],"description":"Feature distribution with filtering","filters":{"collection_id":"my-collection"},"group_by":[{"alias":"feature_type","field":"features.type"}],"having":[{"field":"count","operator":"gte","value":10}],"sort_by":"count","sort_direction":"desc"}]},"DocumentAggregationResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AggregationResult"},"type":"array","title":"Results","description":"List of aggregation results, one per group."},"total_groups":{"type":"integer","title":"Total Groups","description":"Total number of unique groups returned."},"query_info":{"additionalProperties":true,"type":"object","title":"Query Info","description":"Additional information about the query execution. May include collection info, pipeline stages, execution time, etc."}},"type":"object","required":["results","total_groups"],"title":"DocumentAggregationResponse","description":"Response containing document aggregation results.\n\nReturns aggregated statistics grouped by specified fields.","examples":[{"query_info":{"collection_id":"my-collection","execution_time_ms":32,"pipeline_stages":4},"results":[{"group":{"collection":"coll_123"},"metrics":{"total":523}},{"group":{"collection":"coll_456"},"metrics":{"total":187}}],"total_groups":2}]},"DocumentCreateRequest":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"ID of the collection the document belongs to.","example":"collection_123"},"root_object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Object Id","description":"Optional denormalized root object identifier provided during creation."},"root_bucket_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Bucket Id","description":"Optional denormalized bucket identifier provided during creation."},"source_type":{"anyOf":[{"type":"string","enum":["bucket","collection"]},{"type":"null"}],"title":"Source Type","description":"Optional immediate parent type for the document."},"source_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Collection Id","description":"Optional parent collection identifier when sourced from a collection."},"source_document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Document Id","description":"Optional parent document identifier when sourced from a collection."},"source_object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Object Id","description":"Optional parent object identifier when sourced directly from a bucket."},"lineage_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lineage Path","description":"Optional materialized lineage path to set during creation."},"lineage_chain":{"items":{"$ref":"#/components/schemas/LineageStep"},"type":"array","title":"Lineage Chain","description":"Processing steps from root object to this document. Recommended for decomposition trees."},"document_schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Schema Version","description":"Optional document schema version (v1 or v2). If not provided, uses system default."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Optional metadata dictionary for user-defined fields and custom attributes."},"features":{"items":{"$ref":"#/components/schemas/FeatureModel"},"type":"array","title":"Features","description":"Features to associate with the document"}},"additionalProperties":true,"type":"object","required":["collection_id"],"title":"DocumentCreateRequest","description":"Request model for creating a document."},"DocumentGraphExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"document_graph_extractor","title":"Extractor Type","description":"Discriminator field for parameter type identification. Must be 'document_graph_extractor'.","default":"document_graph_extractor"},"use_layout_detection":{"type":"boolean","title":"Use Layout Detection","description":"Enable ML-based layout detection to find ALL document elements (text, images, tables, figures). When enabled, uses the configured layout_detector to detect and extract both text regions AND non-text elements (scanned images, figures, charts) as separate documents. **Recommended for**: Scanned documents, image-heavy PDFs, mixed content documents. **When disabled**: Falls back to text-only extraction (faster but misses images). Default: True (detects all elements including images).","default":true},"layout_detector":{"type":"string","enum":["pymupdf","docling"],"title":"Layout Detector","description":"Layout detection engine to use when use_layout_detection=True. 'pymupdf': Fast, rule-based detection using PyMuPDF heuristics (~15 pages/sec). 'docling': SOTA ML-based detection using IBM Docling with DiT model (~3-8 sec/doc). **Docling advantages**: Better semantic type detection (section_header vs paragraph), true table structure extraction (rows/cols), more accurate figure detection. **PyMuPDF advantages**: Much faster, lower memory usage, simpler dependencies. Default: 'pymupdf' for speed. Use 'docling' for accuracy-critical applications.","default":"pymupdf"},"vertical_threshold":{"type":"number","maximum":100.0,"minimum":1.0,"title":"Vertical Threshold","description":"Maximum vertical gap (in points) between lines to be grouped in same block. Increase for looser grouping, decrease for tighter blocks. Default 15pt works well for standard documents.","default":15.0},"horizontal_threshold":{"type":"number","maximum":200.0,"minimum":1.0,"title":"Horizontal Threshold","description":"Maximum horizontal distance (in points) for overlap detection. Affects column detection and block merging. Increase for wider columns, decrease for narrow layouts.","default":50.0},"min_text_length":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Min Text Length","description":"Minimum text length (characters) to keep a block. Blocks with less text are filtered out. Helps remove noise and tiny fragments.","default":20},"base_confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Base Confidence","description":"Base confidence score for embedded (native) text. Penalties are subtracted for OCR artifacts, encoding issues, etc.","default":0.85},"min_confidence_for_vlm":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Confidence For Vlm","description":"Confidence threshold below which VLM correction is triggered. Blocks with confidence < this value get sent to VLM for correction. Only applies when use_vlm_correction=True.","default":0.6},"use_vlm_correction":{"type":"boolean","title":"Use Vlm Correction","description":"Enable VLM (Vision Language Model) correction for low-confidence blocks. Uses Gemini/GPT-4V to correct OCR errors by analyzing the page image. Significantly slower (~1 page/sec) but improves accuracy for degraded docs.","default":true},"fast_mode":{"type":"boolean","title":"Fast Mode","description":"Skip VLM correction entirely for maximum throughput (~15 pages/sec). Overrides use_vlm_correction. Use when speed is more important than accuracy.","default":false},"vlm_provider":{"type":"string","title":"Vlm Provider","description":"LLM provider for VLM correction. Options: 'google' (Gemini), 'openai' (GPT-4V), 'anthropic' (Claude). Google recommended for best vision quality.","default":"google"},"vlm_model":{"type":"string","title":"Vlm Model","description":"Specific model for VLM correction. Examples: 'gemini-2.5-flash', 'gpt-4o', 'claude-3-5-sonnet'.","default":"gemini-2.5-flash"},"llm_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Api Key","description":"API key for VLM correction (BYOK - Bring Your Own Key). Supports:\n- Direct key: 'sk-proj-abc123...'\n- Secret reference: '{{SECRET.openai_api_key}}'\n\nWhen using secret reference, the key is loaded from your organization's secrets vault at runtime. Store secrets via POST /v1/organizations/secrets.\n\nIf not provided, uses Mixpeek's default API keys."},"run_text_embedding":{"type":"boolean","title":"Run Text Embedding","description":"Generate text embeddings for semantic search over block content. Uses E5-Large (1024-dim) for multilingual support.","default":true},"render_dpi":{"type":"integer","maximum":300.0,"minimum":72.0,"title":"Render Dpi","description":"DPI for page rendering (used for VLM correction). 72: Fast, lower quality. 150: Balanced (recommended). 300: High quality, slower.","default":150},"generate_thumbnails":{"type":"boolean","title":"Generate Thumbnails","description":"Generate thumbnail images for blocks. Useful for visual previews and UI display.","default":true},"thumbnail_mode":{"type":"string","title":"Thumbnail Mode","description":"Thumbnail generation mode. 'full_page': Low-res thumbnail of entire page. 'segment': Cropped thumbnail of just the block's bounding box. 'both': Generate both types (recommended for flexibility).","default":"both"},"thumbnail_dpi":{"type":"integer","maximum":150.0,"minimum":36.0,"title":"Thumbnail Dpi","description":"DPI for thumbnail generation. Lower DPI = smaller files. 72: Standard web quality. 36: Very small thumbnails.","default":72}},"type":"object","title":"DocumentGraphExtractorParams","description":"Parameters for the document graph extractor.\n\nThis extractor decomposes PDFs into spatial blocks with layout classification,\nconfidence scoring, and optional VLM correction for degraded documents.\n\n**When to Use**:\n - Historical/archival document processing (FBI files, old records)\n - Scanned documents with mixed quality\n - Documents requiring spatial understanding (forms, tables, multi-column)\n - When you need block-level granularity with bounding boxes\n - When confidence scoring is needed for downstream filtering\n\n**When NOT to Use**:\n - Simple text-only documents -> Use text_extractor instead\n - When page-level granularity is sufficient -> Use pdf_extractor instead\n - Real-time processing requirements -> VLM correction adds latency","examples":[{"description":"Fast processing mode (no VLM, maximum throughput)","extractor_type":"document_graph_extractor","fast_mode":true,"generate_thumbnails":true,"layout_detector":"pymupdf","run_text_embedding":true,"use_case":"High-volume document ingestion where speed matters more than perfect accuracy","use_layout_detection":true},{"description":"Archival documents with VLM correction (recommended for old scans)","extractor_type":"document_graph_extractor","layout_detector":"pymupdf","min_confidence_for_vlm":0.6,"render_dpi":150,"run_text_embedding":true,"use_case":"Historical archives, FBI files, old scanned documents with degraded quality","use_layout_detection":true,"use_vlm_correction":true,"vlm_model":"gemini-2.5-flash","vlm_provider":"google"},{"description":"SOTA accuracy mode with Docling (best for tables/figures)","extractor_type":"document_graph_extractor","fast_mode":true,"generate_thumbnails":true,"layout_detector":"docling","run_text_embedding":true,"use_case":"Documents with complex tables, figures, or requiring accurate semantic typing","use_layout_detection":true}]},"DocumentGroup":{"properties":{"group_key":{"title":"Group Key","description":"The value that documents in this group share for the group_by field. Can be string, number, boolean, or null depending on the field type. Examples: 'obj_video123' (for source_object_id), 'Electronics' (for metadata.category).","examples":["obj_video123","Electronics","bucket",42,true,null]},"documents":{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array","title":"Documents","description":"List of documents that share the same group_key value. Documents within each group are sorted by relevance/score if applicable. Each document contains full document data including metadata, lineage, and blobs."},"count":{"type":"integer","title":"Count","description":"Number of documents in this group.","examples":[1,5,12]}},"type":"object","required":["group_key","documents","count"],"title":"DocumentGroup","description":"A group of documents with the same field value.\n\nUsed when group_by parameter is specified in ListDocumentsRequest.","examples":[{"count":120,"description":"Group by source_object_id - all frames from one video","documents":[{"collection_id":"col_video_frames","document_id":"doc_frame_001","metadata":{"frame_number":1,"timestamp":0.033},"source_object_id":"obj_video123"},{"collection_id":"col_video_frames","document_id":"doc_frame_002","metadata":{"frame_number":2,"timestamp":0.066},"source_object_id":"obj_video123"}],"group_key":"obj_video123"},{"count":15,"description":"Group by metadata.category - products by category","documents":[{"collection_id":"col_products","document_id":"doc_product_001","metadata":{"category":"Electronics","name":"Laptop"}}],"group_key":"Electronics"}]},"DocumentIdStrategy":{"type":"string","enum":["url","position","content"],"title":"DocumentIdStrategy","description":"Strategy for generating deterministic document IDs.\n\nValues:\n URL: hash(page_url + chunk_index) - stable across re-crawls\n POSITION: hash(seed_url + page_index + chunk_index) - order-based\n CONTENT: hash(content) - deduplicates identical content"},"DocumentListStats":{"properties":{"total_documents":{"type":"integer","title":"Total Documents","description":"Total number of documents in the result","default":0},"avg_blobs_per_document":{"type":"number","title":"Avg Blobs Per Document","description":"Average number of source blobs per document","default":0.0},"total_groups":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Groups","description":"Total number of groups when group_by is used. None for non-grouped results."},"avg_documents_per_group":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Documents Per Group","description":"Average number of documents per group when group_by is used. None for non-grouped results."}},"type":"object","title":"DocumentListStats","description":"Aggregate statistics for a list of documents."},"DocumentResponse":{"properties":{"document_id":{"type":"string","title":"Document Id","description":"REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering.","examples":["doc_f8966ff29c18e20c6b45e053","doc_abc123"]},"collection_id":{"type":"string","title":"Collection Id","description":"REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering.","examples":["col_articles","col_video_frames"]},"document_blobs":{"items":{"$ref":"#/components/schemas/BlobURLRef"},"type":"array","title":"Document Blobs","description":"Document blobs with presigned URLs when requested"},"_internal":{"anyOf":[{"$ref":"#/components/schemas/InternalPayloadModel"},{"type":"null"}],"description":"System-managed internal fields. Contains all Mixpeek-managed metadata including lineage, processing info, timestamps, and blob references. User-defined fields appear at root level alongside document_id and collection_id."},"_vectors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Vectors","description":"List of available named vectors for this document. Only present when return_vector_names=true. Contains sorted vector names stored in Qdrant (e.g., ['fashionsiglip_v1_embedding', 'text_extractor_v1_embedding']). Use individual names with return_vector_names=['name'] to fetch specific embeddings."}},"additionalProperties":true,"type":"object","required":["document_id","collection_id"],"title":"DocumentResponse","description":"Response model for a single document.\n\nThis is the standard response format when fetching documents via API endpoints.\nContains all document data plus optional presigned URLs for S3 blobs.\n\nThe document payload structure follows native Qdrant format:\n - System fields are stored in `_internal` (lineage, metadata, blobs, etc.)\n - User fields are at root level (brand_name, thumbnail_url, etc.)\n - Only document_id and collection_id are Mixpeek IDs at root level\n - No duplication between root and _internal\n\nQuery Parameters Affecting Response:\n - return_url=true: Adds presigned_url to each document_blobs entry\n - return_vectors=true: Includes embedding arrays in response\n\nUse Cases:\n - Display document details in UI\n - Download source files or generated artifacts\n - Understand document provenance and processing\n - Access enrichment fields (flat) for filtering/display","examples":[{"_internal":{"collection_id":"col_articles","created_at":"2025-10-31T10:00:00Z","document_id":"doc_f8966ff29c18e20c6b45e053","internal_id":"org_abc123","lineage":{"chain":[{"collection_id":"col_articles","feature_extractor_id":"text_extractor_v1","timestamp":"2025-10-31T10:00:00Z"}],"path":"bkt_content/col_articles","root_bucket_id":"bkt_content","root_object_id":"obj_article_001","source_object_id":"obj_article_001","source_type":"bucket"},"metadata":{"ingestion_status":"COMPLETED"},"modality":"text","namespace_id":"ns_xyz789","source_blobs":[{"blob_id":"blob_text_001","blob_property":"content","blob_type":"text"}],"updated_at":"2025-10-31T10:00:00Z"},"author":"Dr. Smith","collection_id":"col_articles","description":"Text document with _internal structure","document_id":"doc_f8966ff29c18e20c6b45e053","title":"AI in Healthcare"},{"_internal":{"collection_id":"col_video_frames","created_at":"2025-10-31T10:00:00Z","document_blobs":[{"field":"thumbnail","role":"thumbnail","type":"image","url":"s3://bucket/thumbnails/frame_050.jpg"}],"document_id":"doc_frame_050","internal_id":"org_abc123","lineage":{"path":"bkt_marketing/col_video_frames","root_bucket_id":"bkt_marketing","root_object_id":"obj_video_123","source_object_id":"obj_video_123","source_type":"bucket"},"mime_type":"video/mp4","modality":"video","namespace_id":"ns_xyz789","source_blobs":[{"blob_id":"blob_video_001","blob_property":"video","blob_type":"video"}],"updated_at":"2025-10-31T10:00:00Z"},"campaign_id":"Q4_2025","cluster_distance":0.15,"cluster_id":"cl_marketing","collection_id":"col_video_frames","description":"Video document with user fields and enrichments","document_id":"doc_frame_050","duration":120,"taxonomy_products_label":"Electronics","taxonomy_products_score":0.87},{"_internal":{"collection_id":"col_scenes","created_at":"2025-10-31T10:05:00Z","document_id":"doc_scene_042","internal_id":"org_abc123","lineage":{"chain":[{"collection_id":"col_frames","feature_extractor_id":"multimodal_extractor_v1","timestamp":"2025-10-31T10:00:00Z"},{"collection_id":"col_scenes","feature_extractor_id":"scene_detector_v1","timestamp":"2025-10-31T10:05:00Z"}],"path":"bkt_marketing/col_video_frames/col_scenes","root_bucket_id":"bkt_marketing","root_object_id":"obj_video_123","source_collection_id":"col_video_frames","source_document_id":"doc_frame_050","source_type":"collection"},"modality":"video","namespace_id":"ns_xyz789","updated_at":"2025-10-31T10:05:00Z"},"collection_id":"col_scenes","description":"Multi-tier document (collectionā†’collection)","document_id":"doc_scene_042","end_time":62.3,"scene_type":"action","start_time":45.5}]},"DocumentUpdateRequest":{"properties":{},"additionalProperties":true,"type":"object","title":"DocumentUpdateRequest","description":"Request model for updating a document."},"DrivePropertySource":{"properties":{"type":{"type":"string","const":"drive_property","title":"Type","description":"Source type identifier. Must be 'drive_property' for Google Drive.","default":"drive_property"},"key":{"type":"string","minLength":1,"title":"Key","description":"The property key to extract. Built-in: 'name', 'mimeType', 'description', 'starred', 'createdTime', 'modifiedTime', 'size', 'webViewLink', 'parents'. Custom: Any key set in the file's appProperties. Case-sensitive.","examples":["description","starred","category","modifiedTime"]}},"type":"object","required":["key"],"title":"DrivePropertySource","description":"Extract value from Google Drive file properties.\n\nGoogle Drive files have built-in properties (name, mimeType, etc.) and\ncustom properties (appProperties). This source extracts from either.\n\nProvider Compatibility: Google Drive, Google Workspace Shared Drives\n\nBuilt-in properties:\n - name: File name\n - mimeType: MIME type\n - description: File description\n - starred: Boolean star status\n - trashed: Boolean trash status\n - createdTime: Creation timestamp\n - modifiedTime: Last modified timestamp\n - size: File size in bytes\n\nCustom properties: Set via Drive API appProperties field\n\nExample mapping:\n {\"type\": \"drive_property\", \"key\": \"description\"} -> extracts file description\n\nAttributes:\n type: Must be \"drive_property\" to identify this source type\n key: The property key to extract (case-sensitive)"},"DurationStats":{"properties":{"mean":{"type":"number","title":"Mean","description":"Average duration in seconds"},"median":{"type":"number","title":"Median","description":"Median duration in seconds"},"p50":{"type":"number","title":"P50","description":"50th percentile (same as median)"},"p90":{"type":"number","title":"P90","description":"90th percentile duration in seconds"},"p95":{"type":"number","title":"P95","description":"95th percentile duration in seconds"},"std_dev":{"type":"number","title":"Std Dev","description":"Standard deviation in seconds"},"min":{"type":"number","title":"Min","description":"Minimum duration observed in seconds"},"max":{"type":"number","title":"Max","description":"Maximum duration observed in seconds"}},"type":"object","required":["mean","median","p50","p90","p95","std_dev","min","max"],"title":"DurationStats","description":"Statistical distribution of durations for successful step transitions.\n\nProvides comprehensive percentile analysis to understand timing patterns.\n\nAttributes:\n mean: Average duration (seconds)\n median: Middle value (50th percentile)\n p50: 50th percentile (same as median, included for consistency)\n p90: 90th percentile (90% complete faster)\n p95: 95th percentile (95% complete faster)\n std_dev: Standard deviation (measure of spread)\n min: Fastest observed duration\n max: Slowest observed duration\n\nExample:\n ```python\n DurationStats(\n mean=432000.0, # 5 days average\n median=345600.0, # 4 days median\n p50=345600.0,\n p90=691200.0, # 8 days (90th percentile)\n p95=864000.0, # 10 days (95th percentile)\n std_dev=172800.0, # 2 days std dev\n min=86400.0, # 1 day minimum\n max=1209600.0 # 14 days maximum\n )\n ```"},"DynamicValue":{"properties":{"type":{"type":"string","const":"dynamic","title":"Type","default":"dynamic"},"field":{"type":"string","title":"Field","description":"The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'","examples":["inputs.query_text","filters.AND[0].value"]}},"type":"object","required":["field"],"title":"DynamicValue","description":"A value that should be dynamically resolved from the query request."},"EmailConfig":{"properties":{"to_addresses":{"items":{"type":"string"},"type":"array","title":"To Addresses","description":"Email addresses to send to"},"subject_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Template","description":"Template for email subject"},"body_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Template","description":"Template for email body"},"content_type":{"$ref":"#/components/schemas/NotificationContentType","description":"Format of the email body","default":"html"},"cc_addresses":{"items":{"type":"string"},"type":"array","title":"Cc Addresses","description":"CC addresses"},"bcc_addresses":{"items":{"type":"string"},"type":"array","title":"Bcc Addresses","description":"BCC addresses"}},"type":"object","required":["to_addresses"],"title":"EmailConfig","description":"Configuration for email notifications."},"EnableOrgModelRequest":{"properties":{"deploy":{"type":"boolean","title":"Deploy","description":"Whether to deploy the model to Ray immediately after enabling","default":false},"resource_overrides":{"anyOf":[{"$ref":"#/components/schemas/ModelResourceRequirements"},{"type":"null"}],"description":"Override resource requirements for this namespace deployment"}},"type":"object","title":"EnableOrgModelRequest","description":"Request to enable an org-level model for a namespace."},"EnableOrgModelResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether operation succeeded"},"model_id":{"type":"string","title":"Model Id","description":"Model identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace where model was enabled"},"deployment_status":{"type":"string","title":"Deployment Status","description":"Deployment status (deployed, pending, skipped)"},"message":{"type":"string","title":"Message","description":"Status message"}},"type":"object","required":["success","model_id","namespace_id","deployment_status","message"],"title":"EnableOrgModelResponse","description":"Response from enabling an org-level model for a namespace."},"EnableOrgPluginRequest":{"properties":{"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Params","description":"Optional parameters to configure the plugin for this namespace"},"deploy":{"type":"boolean","title":"Deploy","description":"Whether to deploy the plugin to Ray immediately after enabling","default":true}},"type":"object","title":"EnableOrgPluginRequest","description":"Request to enable an org-level plugin for a namespace.\n\nThis adds the plugin to the namespace's feature_extractors array,\nmaking it available for use in collections within this namespace."},"EnableOrgPluginResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the operation succeeded"},"plugin_id":{"type":"string","title":"Plugin Id","description":"The plugin ID that was enabled"},"namespace_id":{"type":"string","title":"Namespace Id","description":"The namespace where plugin was enabled"},"feature_uri":{"type":"string","title":"Feature Uri","description":"Feature URI to use in collections"},"message":{"type":"string","title":"Message","description":"Status message"},"deployment_status":{"anyOf":[{"type":"string","enum":["deployed","pending","skipped"]},{"type":"null"}],"title":"Deployment Status","description":"Deployment status if deploy=True"}},"type":"object","required":["success","plugin_id","namespace_id","feature_uri","message"],"title":"EnableOrgPluginResponse","description":"Response from enabling an org-level plugin for a namespace."},"EnginePerformanceResponse":{"properties":{"time_range":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Time range of the query"},"metrics":{"items":{"$ref":"#/components/schemas/PerformanceMetric"},"type":"array","title":"Metrics","description":"Time-series performance metrics"},"summary":{"anyOf":[{"$ref":"#/components/schemas/PerformanceSummary"},{"type":"null"}],"description":"Overall summary statistics"}},"type":"object","required":["time_range","metrics"],"title":"EnginePerformanceResponse","description":"Response for engine performance query."},"EngineStageBreakdownResponse":{"properties":{"time_range":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Time range of the analysis"},"stages":{"items":{"$ref":"#/components/schemas/StagePerformance-Output"},"type":"array","title":"Stages","description":"Performance breakdown by stage"},"total_time_ms":{"type":"number","title":"Total Time Ms","description":"Total time across all stages (sum)"}},"type":"object","required":["time_range","stages","total_time_ms"],"title":"EngineStageBreakdownResponse","description":"Response for engine stage breakdown."},"EnrichmentField":{"properties":{"field_path":{"type":"string","title":"Field Path","description":"Dot-notation path of the field to copy from the taxonomy node."},"target_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Field","description":"Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label ā†’ visual_style).","examples":["visual_style","style_description","brand_name"]},"merge_mode":{"$ref":"#/components/schemas/EnrichmentMergeMode","description":"Whether to overwrite the target's value or append (for arrays).","default":"replace"}},"type":"object","required":["field_path"],"title":"EnrichmentField","description":"Field-level enrichment behaviour specification.\n\nDefines how to copy fields from taxonomy source nodes to enriched documents.\nSupports field renaming via target_field parameter.\n\nExamples:\n - Copy field as-is: {\"field_path\": \"category\", \"merge_mode\": \"replace\"}\n - Rename field: {\"field_path\": \"label\", \"target_field\": \"visual_style\", \"merge_mode\": \"replace\"}\n - Append to array: {\"field_path\": \"tags\", \"merge_mode\": \"append\"}","examples":[{"field_path":"metadata.tags","merge_mode":"append"},{"field_path":"category","merge_mode":"replace"},{"field_path":"label","merge_mode":"replace","target_field":"visual_style"},{"field_path":"description","merge_mode":"replace","target_field":"style_description"}]},"EnrichmentFieldMapping":{"properties":{"source_field":{"type":"string","title":"Source Field","description":"Field from cluster results to include. Available fields: cluster_id, cluster_label, distance_to_centroid, member_count, keywords, x, y, z (visualization coords), metadata.*"},"target_field":{"type":"string","title":"Target Field","description":"Target field name in enriched document. Example: 'category_id' for cluster_id, 'product_category' for cluster_label"}},"type":"object","required":["source_field","target_field"],"title":"EnrichmentFieldMapping","description":"Maps a cluster result field to a document enrichment field.\n\nSimilar to InputMapping pattern used throughout Mixpeek."},"EnrichmentHistoryResponse":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__taxonomies__models__TimeRange"},"metrics":{"items":{"$ref":"#/components/schemas/EnrichmentMetric"},"type":"array","title":"Metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"}},"type":"object","required":["taxonomy_id","time_range","metrics"],"title":"EnrichmentHistoryResponse","description":"Taxonomy enrichment history response."},"EnrichmentInputMapping":{"properties":{"input_key":{"type":"string","title":"Input Key","description":"The retriever input parameter name","examples":["query","query_embedding","collection_id"]},"source":{"$ref":"#/components/schemas/InputMappingSource","description":"Where to get the value from (document field or constant)"}},"type":"object","required":["input_key","source"],"title":"EnrichmentInputMapping","description":"Maps a document field or constant to a retriever input parameter.\n\nDefines how to construct retriever inputs from the document being enriched.\n\nAttributes:\n input_key: The retriever input parameter name\n source: Where to get the value from (document field or constant)","examples":[{"input_key":"query","source":{"path":"title","source_type":"document_field"}},{"input_key":"collection_id","source":{"source_type":"constant","value":"col_reference_data"}}]},"EnrichmentMergeMode":{"type":"string","enum":["replace","append"],"title":"EnrichmentMergeMode","description":"How a field from the taxonomy node should be merged into the target doc."},"EnrichmentMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket"},"enrichment_count":{"type":"integer","title":"Enrichment Count"},"success_count":{"type":"integer","title":"Success Count"},"failure_count":{"type":"integer","title":"Failure Count"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms"},"success_rate":{"type":"number","title":"Success Rate"}},"type":"object","required":["time_bucket","enrichment_count","success_count","failure_count","avg_latency_ms","success_rate"],"title":"EnrichmentMetric","description":"Taxonomy enrichment metrics."},"ErrorBreakdown":{"properties":{"error_type":{"type":"string","title":"Error Type","description":"Error type"},"count":{"type":"integer","title":"Count","description":"Error count"},"percentage":{"type":"number","title":"Percentage","description":"Percentage of total errors"},"first_seen":{"type":"string","format":"date-time","title":"First Seen","description":"First occurrence"},"last_seen":{"type":"string","format":"date-time","title":"Last Seen","description":"Last occurrence"}},"type":"object","required":["error_type","count","percentage","first_seen","last_seen"],"title":"ErrorBreakdown","description":"Error breakdown by type."},"ErrorCategory":{"type":"string","enum":["dependency","authentication","validation","runtime","network","resource"],"title":"ErrorCategory","description":"Categories for batch processing errors.\n\nUsed to classify errors for better observability, retry logic, and debugging.\nHelps distinguish between transient errors (worth retrying) and permanent errors."},"ErrorDetail":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"},"type":{"type":"string","title":"Type","description":"Stable error type identifier (machine-readable)"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Optional structured details to help debugging (validation errors, IDs, etc.)"}},"type":"object","required":["message","type"],"title":"ErrorDetail","description":"Error detail model."},"ErrorMetrics":{"properties":{"error_type":{"type":"string","title":"Error Type"},"count":{"type":"integer","title":"Count"},"percentage":{"type":"number","title":"Percentage"},"recent_message":{"type":"string","title":"Recent Message"}},"type":"object","required":["error_type","count","percentage","recent_message"],"title":"ErrorMetrics","description":"Error analysis metrics."},"ErrorResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Always false for error responses","default":false},"status":{"type":"integer","title":"Status","description":"HTTP status code for this error"},"error":{"$ref":"#/components/schemas/ErrorDetail","description":"Error details payload"}},"type":"object","required":["status","error"],"title":"ErrorResponse","description":"Error response model.","examples":[{"error":{"details":{"id":"ns_123","resource":"namespace"},"message":"Namespace not found","type":"NotFoundError"},"status":404,"success":false}]},"EvaluationConfig":{"properties":{"k_values":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"K Values","description":"K values for Precision@K, Recall@K, NDCG@K, etc.","default":[1,5,10,20]},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metrics","description":"List of metrics to calculate. Available: precision, recall, f1, map, ndcg, mrr","default":["precision","recall","f1","map","ndcg","mrr"]}},"type":"object","title":"EvaluationConfig","description":"Configuration for an evaluation run."},"EvaluationDataset":{"properties":{"dataset_id":{"type":"string","title":"Dataset Id","description":"Unique dataset identifier"},"dataset_name":{"type":"string","title":"Dataset Name","description":"Human-readable dataset name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Dataset description"},"queries":{"items":{"$ref":"#/components/schemas/GroundTruthQuery"},"type":"array","title":"Queries","description":"List of queries with ground truth"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When dataset was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace this dataset belongs to"},"internal_id":{"type":"string","title":"Internal Id","description":"Internal organization ID"},"query_count":{"type":"integer","title":"Query Count","description":"Number of queries in dataset"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional metadata (e.g., labeling instructions, version info)"}},"type":"object","required":["dataset_id","dataset_name","queries","created_at","updated_at","namespace_id","internal_id","query_count"],"title":"EvaluationDataset","description":"Complete evaluation dataset with metadata.\n\nAn evaluation dataset is a collection of queries with ground truth relevance labels,\nused to measure retriever quality."},"EvaluationListResponse":{"properties":{"evaluations":{"items":{"$ref":"#/components/schemas/EvaluationRecord"},"type":"array","title":"Evaluations","description":"List of evaluations"},"total":{"type":"integer","title":"Total","description":"Total count"},"page":{"type":"integer","title":"Page","description":"Current page"},"page_size":{"type":"integer","title":"Page Size","description":"Page size"}},"type":"object","required":["evaluations","total","page","page_size"],"title":"EvaluationListResponse","description":"Response for listing evaluations."},"EvaluationRecord":{"properties":{"evaluation_id":{"type":"string","title":"Evaluation Id","description":"Unique evaluation identifier"},"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of retriever being evaluated"},"dataset_id":{"type":"string","title":"Dataset Id","description":"ID of dataset used for evaluation"},"dataset_name":{"type":"string","title":"Dataset Name","description":"Name of dataset"},"config":{"$ref":"#/components/schemas/EvaluationConfig","description":"Evaluation configuration"},"status":{"$ref":"#/components/schemas/EvaluationStatus","description":"Current status"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When evaluation was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When evaluation completed"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"internal_id":{"type":"string","title":"Internal Id","description":"Internal organization ID"},"query_count":{"type":"integer","title":"Query Count","description":"Number of queries evaluated"},"overall_metrics":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Overall Metrics","description":"Aggregated metrics across all queries"},"metrics_by_k":{"anyOf":[{"additionalProperties":{"additionalProperties":{"type":"number"},"type":"object"},"type":"object"},{"type":"null"}],"title":"Metrics By K","description":"Metrics broken down by K value (keys are string K values like '5', '10', '20')"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if failed"}},"type":"object","required":["evaluation_id","retriever_id","dataset_id","dataset_name","config","status","created_at","updated_at","namespace_id","internal_id","query_count"],"title":"EvaluationRecord","description":"Complete evaluation record with results."},"EvaluationStatus":{"type":"string","enum":["pending","in_progress","completed","failed"],"title":"EvaluationStatus","description":"Status of an evaluation run."},"ExecuteRetrieverRequest":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Runtime inputs for the retriever mapped to the input schema. Keys must match the retriever's input_schema field names. Values depend on field types (text, vector, filters, etc.). REQUIRED unless all retriever inputs have defaults. \n\nCommon input keys:\n- 'query': Text search query\n- 'embedding': Pre-computed vector for search\n- 'top_k': Number of results to return\n- 'min_score': Minimum relevance threshold\n- Any custom fields defined in input_schema\n\n\n**Template Syntax** (Jinja2):\n\nNamespaces (uppercase or lowercase):\n- `INPUT` / `input`: Query inputs (e.g., `{{INPUT.query}}`)\n- `DOC` / `doc`: Document fields (e.g., `{{DOC.payload.title}}`)\n- `CONTEXT` / `context`: Execution context\n- `STAGE` / `stage`: Stage configuration\n- `SECRET` / `secret`: Vault secrets (e.g., `{{SECRET.api_key}}`)\n\nAccessing Data:\n- Dot notation: `{{DOC.payload.metadata.title}}`\n- Bracket notation: `{{DOC.payload['special-key']}}`\n- Array index: `{{DOC.items[0]}}`, `{{DOC.tags[2]}}`\n- Array first/last: `{{DOC.items | first}}`, `{{DOC.items | last}}`\n\nArray Operations:\n- Iterate: `{% for item in DOC.tags %}{{item}}{% endfor %}`\n- Extract key: `{{DOC.items | map(attribute='name') | list}}`\n- Join: `{{DOC.tags | join(', ')}}`\n- Length: `{{DOC.items | length}}`\n- Slice: `{{DOC.items[:5]}}`\n\nConditionals:\n- If: `{% if DOC.status == 'active' %}...{% endif %}`\n- If-else: `{% if DOC.score > 0.8 %}high{% else %}low{% endif %}`\n- Ternary: `{{'yes' if DOC.enabled else 'no'}}`\n\nBuilt-in Functions: `max`, `min`, `abs`, `round`, `ceil`, `floor`\nCustom Filters: `slugify` (URL-safe), `bool` (truthy coercion), `tojson` (JSON encode)\n\nS3 URLs: Internal S3 URLs (s3://bucket/key) are automatically presigned when accessed via DOC namespace.","examples":[{"query":"artificial intelligence","top_k":25},{"min_score":0.7,"query":"customer feedback","top_k":50},{"category":"blog","embedding":[0.1,0.2,0.3],"top_k":10}]},"pagination":{"anyOf":[{"$ref":"#/components/schemas/OffsetPaginationParams"},{"$ref":"#/components/schemas/CursorPaginationParams"},{"$ref":"#/components/schemas/ScrollPaginationParams"},{"$ref":"#/components/schemas/KeysetPaginationParams"}],"title":"Pagination","description":"Pagination strategy configuration. Defaults to cursor-based pagination with limit=20. \n\nIMPORTANT: Pagination params do NOT support template variables ({{INPUT.x}} or {{DOCUMENT.x}}). Pagination is a request-level parameter for slicing results, separate from pipeline business logic. Pass cursor/limit values directly from your client code. Cursor values come from the previous response's pagination.cursor field.\n\nSupported Methods:\n- CURSOR (default): Best for infinite scroll, stateless, opaque token\n- KEYSET: Most efficient, requires stable sort, stateless\n- OFFSET: Traditional page numbers, can have drift issues\n- SCROLL: Server-side state, best for bulk exports\n\n\nUse CURSOR for:\n- Infinite scroll UIs (mobile apps, feeds, timelines)\n- Real-time updates where consistency matters\n- When you can't jump to arbitrary pages\n\n\nUse KEYSET for:\n- Maximum performance with large result sets\n- Stable sort fields (e.g., score DESC, id ASC)\n- When you need truly stateless pagination\n\n\nUse OFFSET for:\n- Traditional page UIs with page numbers\n- When users need to jump to specific pages\n- Smaller result sets where drift is acceptable\n\n\nUse SCROLL for:\n- Bulk exports or processing large datasets\n- When you need to iterate through all results\n- Background jobs with progress tracking\n\n\nExample (cursor - first page):\n{\"method\": \"cursor\", \"limit\": 20, \"cursor\": null}\n\nExample (cursor - next page, using cursor from previous response):\n{\"method\": \"cursor\", \"limit\": 20, \"cursor\": \"eyJvZmZzZXQiOjIwfQ==\"}\n\nExample (offset):\n{\"method\": \"offset\", \"page_size\": 25, \"page_number\": 2}\n\nExample (keyset):\n{\"method\": \"keyset\", \"limit\": 20, \"after\": {\"score\": 0.73, \"id\": \"doc_20\"}}\n"},"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 uses text/event-stream content type\n- Each stage completion emits a StreamStageEvent\n- Events include: stage_start, stage_complete, stage_error, execution_complete\n- Clients receive intermediate results and statistics as stages execute\n- Useful for progress tracking, debugging, and partial result display\n\n\nWhen stream=False (default):\n- Response returns after all stages complete\n- Returns a single RetrieverExecutionResponse with final results\n- Lower overhead for simple queries\n\n\nUse streaming when:\n- You want to show real-time progress to users\n- You need to display intermediate results\n- Pipeline has many stages or long-running operations\n- Debugging or monitoring pipeline performance\n\n\nExample streaming client (JavaScript):\n```javascript\nconst eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true');\neventSource.onmessage = (event) => {\n const stageEvent = JSON.parse(event.data);\n if (stageEvent.event_type === 'stage_complete') {\n console.log(`Stage ${stageEvent.stage_name} completed`);\n console.log(`Documents: ${stageEvent.documents.length}`);\n }\n};\n```\n\n\nExample streaming client (Python):\n```python\nimport requests\nresponse = requests.post('/v1/retrievers/ret_123/execute',\n json={'inputs': {...}, 'stream': True},\n stream=True)\nfor line in response.iter_lines():\n if line.startswith(b'data: '):\n event = json.loads(line[6:])\n print(f\"Stage {event['stage_name']}: {event['event_type']}\")\n```","default":false,"examples":[false,true]}},"type":"object","title":"ExecuteRetrieverRequest","description":"Request to execute a retriever with optional streaming support.\n\nInherits all fields from RetrieverExecutionRequest including:\n- inputs: Runtime input values matching the retriever's input_schema\n- pagination: Pagination configuration (cursor, offset, etc.)\n- stream: Enable SSE streaming for real-time stage updates\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, counts, etc.)\n - budget_used: Cumulative resource consumption\n\n Example streaming client:\n ```python\n response = requests.post(\n '/v1/retrievers/{id}/execute',\n json={'inputs': {...}, 'stream': True},\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.","examples":[{"description":"Simple query","inputs":{"query":"artificial intelligence trends","top_k":25}},{"description":"Query with stage-driven filtering via inputs","inputs":{"categories":["AI","ML"],"min_score":0.7,"published_after":"2024-01-01","query":"machine learning","top_k":100}},{"description":"Advanced query with multiple input parameters","inputs":{"date_range":{"end":"2024-12-31","start":"2024-01-01"},"query":"customer testimonials","sentiment":"positive","top_k":20}},{"description":"Infinite scroll with cursor pagination (first page)","inputs":{"query":"AI trends","top_k":50},"pagination":{"limit":20,"method":"cursor"}},{"description":"Infinite scroll (next page using cursor from previous response)","inputs":{"query":"AI trends","top_k":50},"pagination":{"cursor":"eyJvZmZzZXQiOjIwfQ==","limit":20,"method":"cursor"}},{"description":"Traditional pagination with page numbers","inputs":{"query":"ML papers"},"pagination":{"method":"offset","page_number":2,"page_size":25}},{"description":"High-performance keyset pagination","inputs":{"query":"customer reviews","top_k":100},"pagination":{"after":{"id":"doc_20","score":0.73},"limit":20,"method":"keyset"}},{"description":"Scroll pagination for bulk export","inputs":{"query":"all documents"},"pagination":{"limit":100,"method":"scroll","scroll_ttl":300}}]},"ExecuteTaxonomyRequest":{"properties":{"taxonomy":{"$ref":"#/components/schemas/TaxonomyModel-Input","description":"Full taxonomy model with configuration (fetched from DB by controller)"},"retriever":{"anyOf":[{"$ref":"#/components/schemas/RetrieverModel-Input"},{"type":"null"}],"description":"Optional retriever configuration override for testing. If omitted, uses the retriever configured in the taxonomy."},"source_documents":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Source Documents","description":"Sample documents to test enrichment (typically 1-5 docs). Results are returned immediately, not persisted. āš ļø Do NOT pass collection_id expecting batch processing!"},"source_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Collection Id","description":"āš ļø IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. To enrich collections, use taxonomy_applications on the collection."},"target_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Collection Id","description":"āš ļø IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. Results are never persisted via this endpoint."},"join_mode":{"$ref":"#/components/schemas/JoinMode","description":"Must be 'on_demand'. BATCH mode is NOT supported via API. Batch enrichment is automatic (triggered by engine during ingestion).","default":"on_demand"},"batch_size":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Batch Size","description":"Batch size for the scroll iterator","default":1000},"scroll_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Additional filters applied to the source collection prior to enrichment."}},"type":"object","required":["taxonomy"],"title":"ExecuteTaxonomyRequest","description":"Request model for on-demand taxonomy validation and testing ONLY.\n\nāš ļø IMPORTANT: This endpoint is ONLY for testing taxonomy configuration with sample documents.\n\nDO NOT USE THIS FOR BATCH ENRICHMENT:\nāŒ Do NOT use this to enrich an entire collection\nāŒ Do NOT use source_collection_id expecting batch processing\nāŒ Do NOT use target_collection_id expecting persistence\n\nHOW TAXONOMY ENRICHMENT ACTUALLY WORKS:\nāœ… Automatic during ingestion: Attach taxonomies to collections via `taxonomy_applications`\nāœ… On-the-fly in retrieval: Add `taxonomy_join` stage to retriever pipelines\n\nThis endpoint validates:\n- Taxonomy configuration is correct\n- Retriever can find matching taxonomy nodes\n- Enrichment fields are properly applied\n\nFor production enrichment, see:\n- Collections API: attach taxonomies via `taxonomy_applications` field\n- Retrievers API: add `taxonomy_join` stage for on-the-fly enrichment","examples":[{"batch_size":1000,"join_mode":"on_demand","source_collection_id":"col_catalog_v2","target_collection_id":"col_catalog_enriched_v2","taxonomy":{"config":{"input_mappings":[{"input_key":"image_vector","path":"features.clip","source_type":"vector"}],"retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1"},"taxonomy_type":"flat"},"input_mappings":[{"input_key":"image_vector","path":"features.clip","source_type":"vector"}],"namespace_id":"ns_123","retriever_id":"ret_clip_v1","taxonomy_name":"product_tags"}}]},"ExecutionDetail":{"properties":{"execution_id":{"type":"string","title":"Execution Id","description":"REQUIRED. Unique identifier for this execution run. Use this ID to track execution status, retrieve execution details, or query execution history. Format: 'exec_' prefix followed by alphanumeric token.","examples":["exec_abc123def456","exec_xyz789"]},"status":{"type":"string","title":"Status","description":"REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry.","examples":["completed","failed","processing"]},"documents":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Documents","description":"REQUIRED. Final document results after retriever completion. Contains documents that passed through all retriever stages. Each document may include: document_id, payload (full document data), score (relevance score), metadata (collection-specific fields), and any fields added by enrichment/join stages. Empty array indicates no documents matched the query criteria. Note: Legacy format may use 'final_results' instead of 'documents'.","examples":[[{"document_id":"doc_123","payload":{"metadata":{"category":"AI"},"text":"Sample content"},"score":0.95},{"document_id":"doc_456","payload":{"metadata":{"category":"ML"},"text":"Another document"},"score":0.88}]]},"pagination":{"additionalProperties":true,"type":"object","title":"Pagination","description":"REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset pagination: {total, limit, offset, has_next, has_previous}, Cursor pagination: {cursor, has_next, page_size}, Keyset pagination: {next_cursor, has_next}. Use this to navigate through result pages.","examples":[{"has_next":true,"limit":10,"offset":0,"total":100},{"cursor":"abc123","has_next":false,"page_size":20}]},"stage_statistics":{"$ref":"#/components/schemas/RetrieverExecutionStatistics","description":"REQUIRED. Per-stage execution statistics including timing, document counts, cache hit rates, and stage-specific metrics. Use this to understand retriever performance and identify bottlenecks."},"budget":{"additionalProperties":true,"type":"object","title":"Budget","description":"REQUIRED. Budget usage snapshot for this execution. Contains: credits_used (credits consumed), credits_remaining (remaining budget), time_used_ms (execution time), and budget limits. Use this to track resource consumption and enforce budget limits.","examples":[{"credits_remaining":99.5,"credits_used":0.5,"time_used_ms":150}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"OPTIONAL. Retriever-level error message if execution failed. Only present when status='failed'. Contains human-readable error description to help diagnose the failure. Check stage_statistics for stage-specific errors.","examples":["Retriever execution failed: Collection not found","Budget exceeded: Maximum credits limit reached"]},"optimization_applied":{"type":"boolean","title":"Optimization Applied","description":"OPTIONAL. Whether automatic pipeline optimizations were applied before execution. Mixpeek automatically optimizes retrieval pipelines for performance by reordering stages, merging operations, and pushing work to the database layer. Optimizations preserve logical equivalence - you get the same results, just faster. When true, see optimization_summary for details about what changed.","default":false,"examples":[true,false]},"optimization_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Optimization Summary","description":"OPTIONAL. Summary of pipeline optimizations applied before execution. Only present when optimization_applied=true. Contains: - original_stage_count: Number of stages in your original pipeline - optimized_stage_count: Number of stages after optimization - optimization_time_ms: Time spent optimizing (typically <100ms) - rules_applied: List of optimization rules that fired - stage_reduction_pct: Percentage reduction in stage count Use this to understand how the optimizer improved your pipeline. See OptimizationRuleType enum for detailed rule descriptions.","examples":[{"optimization_time_ms":8.2,"optimized_stage_count":3,"original_stage_count":5,"rules_applied":["push_down_filters","group_by_push_down"],"stage_reduction_pct":40.0},{"optimization_time_ms":2.1,"optimized_stage_count":3,"original_stage_count":3,"rules_applied":[],"stage_reduction_pct":0.0}]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when execution began"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Timestamp when execution finished"},"current_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Stage","description":"Stage currently running when execution in-flight"},"stages_completed":{"type":"integer","minimum":0.0,"title":"Stages Completed","description":"Number of stages finished so far","default":0},"total_stages":{"type":"integer","minimum":0.0,"title":"Total Stages","description":"Total stages configured","default":0}},"type":"object","required":["execution_id","status"],"title":"ExecutionDetail","description":"Alias wrapper for execution detail documentation."},"ExecutionHistoryResponse":{"properties":{"cluster_id":{"type":"string","title":"Cluster Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__clusters__models__TimeRange"},"results":{"items":{"$ref":"#/components/schemas/ClusterExecutionMetric"},"type":"array","title":"Results"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"}},"type":"object","required":["cluster_id","time_range","results"],"title":"ExecutionHistoryResponse","description":"Cluster execution history response."},"ExplainRetrieverRequest":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Hypothetical inputs for tailored execution plan estimation. These values are used to analyze stage behavior and estimate costs. \n\nNOT REQUIRED - if omitted, default/representative values are used. \n\nCommon inputs:\n- 'query': Search query text (for semantic search stages)\n- 'top_k': Number of results to return (affects search scope)\n- Filter parameters: Category, price range, etc.\n\n\nExamples:\n- {'query': 'laptop'} - Simple text query\n- {'query': 'laptop', 'top_k': 100} - Query with custom limit\n- {'query': 'laptop', 'category': 'electronics', 'price_max': 1000} - Query with filters\n\n\nNote: Inputs are for estimation only. No actual search is performed.","examples":[{"query":"test query","top_k":50},{"category":"electronics","query":"wireless headphones"},{"embedding":[0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.1],"top_k":100},{}]}},"type":"object","title":"ExplainRetrieverRequest","description":"Request to get execution plan for a retriever.\n\nProvides optional hypothetical inputs to tailor the execution plan estimation.\nThe explain endpoint analyzes your retriever configuration and returns cost/latency\nestimates without actually executing the query.\n\nUse Cases:\n - See how plan changes with different input values\n - Estimate costs for different query patterns\n - Understand impact of parameter changes (e.g., top_k)\n - Test stage behavior with representative inputs\n\nBehavior:\n - If inputs are provided, they're used for tailored estimation\n - If inputs are not provided, default/representative values are used\n - Inputs do NOT need to match your input_schema exactly\n - No actual retrieval is performed (explain is analysis only)","examples":[{"description":"Explain with simple query input","inputs":{"query":"machine learning tutorials"}},{"description":"Explain with query and custom limit","inputs":{"query":"red sports car","top_k":100}},{"description":"Explain with multiple filter parameters","inputs":{"category":"electronics","price_max":200,"query":"wireless headphones"}},{"description":"Explain with default inputs (empty)","inputs":{}}]},"ExplainRetrieverResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Unique identifier of the retriever being explained. REQUIRED.","examples":["ret_abc123","ret_product_search_v2"]},"retriever_name":{"type":"string","title":"Retriever Name","description":"Human-readable name of the retriever. REQUIRED.","examples":["product_search","customer_lookup"]},"estimated_cost":{"additionalProperties":{"type":"number"},"type":"object","title":"Estimated Cost","description":"Estimated total cost breakdown for executing this retriever. Contains: 'total_credits' (credit cost), 'total_duration_ms' (latency). Sum of all stage costs. Use for budget planning. REQUIRED.","examples":[{"total_credits":0.51,"total_duration_ms":220.0},{"total_credits":15.5,"total_duration_ms":8500.0}]},"execution_plan":{"items":{"$ref":"#/components/schemas/ExplainStagePlan"},"type":"array","title":"Execution Plan","description":"Ordered list of stage execution plans showing the OPTIMIZED pipeline. Each entry shows cost, latency, document flow, and warnings for one stage. Stages execute in this order. REQUIRED (may be empty for invalid retrievers)."},"optimization_suggestions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Optimization Suggestions","description":"Actionable suggestions for improving retriever performance. Each suggestion includes: 'type' (suggestion category), 'stage' (affected stage name), 'message' (human-readable description). Common types: 'reduce_limit', 'add_filter', 'reorder_stages', 'enable_cache'. OPTIONAL (empty if no suggestions).","examples":[[{"message":"Consider reducing limit from 1000 to 100 to improve latency","stage":"semantic_search","type":"reduce_limit"},{"message":"Add attribute filter before this expensive stage","stage":"llm_quality_filter","type":"add_filter"}]]},"total_estimated_stages":{"type":"integer","minimum":0.0,"title":"Total Estimated Stages","description":"Total number of stages in the optimized execution plan. This may differ from your original stage count if optimizations were applied. Compare with optimization_details.original_stage_count to see reduction. REQUIRED.","examples":[2,5,10]},"bottleneck_stages":{"items":{"type":"string"},"type":"array","title":"Bottleneck Stages","description":"Names of stages expected to dominate execution time. Includes stages with duration >= 80%% of the slowest stage. Focus optimization efforts on these stages. OPTIONAL (empty if all stages have similar duration).","examples":[["semantic_search"],["llm_quality_filter","rerank"]]},"optimization_level":{"type":"string","title":"Optimization Level","description":"Optimization level applied by the optimizer. Values: 'none' (no optimization), 'mvp' (basic optimizations), 'advanced' (all optimizations). REQUIRED.","default":"mvp","examples":["none","mvp","advanced"]},"optimization_applied":{"type":"boolean","title":"Optimization Applied","description":"Whether automatic pipeline optimizations were applied. When true, execution_plan shows OPTIMIZED stages (after transformations like filter push-down, stage fusion, grouping optimization). When false, execution_plan matches your original configuration. Check optimization_details to see what changed. REQUIRED.","default":false},"optimization_details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Optimization Details","description":"Detailed breakdown of optimization transformations applied. Only present when optimization_applied=true. \n\nFields:\n- original_stage_count: Stage count before optimization\n- optimized_stage_count: Stage count after optimization\n- optimization_time_ms: Time spent on optimization (typically <100ms)\n- stage_reduction_pct: Percentage reduction in stage count\n- decisions: Array of optimization decisions\n\n\nEach decision contains:\n- rule_type: Optimization rule that fired\n- applied: Whether the rule was applied\n- reason: Human-readable explanation\n- stages_before/after: Stage counts before/after this rule\n\n\nCommon rule types:\n- push_down_filters: Move filters earlier to reduce downstream work\n- group_by_push_down: Push grouping to database layer (10-100x faster)\n- merge_consecutive_filters: Combine adjacent filters\n- eliminate_redundant_sorts: Remove duplicate sort operations\n\n\nOPTIONAL (null when optimization_applied=false).","examples":[{"decisions":[{"applied":true,"reason":"Moved attribute_filter before semantic_search to reduce search scope by 50%","rule_type":"push_down_filters","stages_after":5,"stages_before":5},{"applied":true,"reason":"Merged group_by into feature_filter for database-level grouping (10x faster)","rule_type":"group_by_push_down","stages_after":3,"stages_before":5}],"optimization_time_ms":8.2,"optimized_stage_count":3,"original_stage_count":5,"stage_reduction_pct":40.0}]}},"type":"object","required":["retriever_id","retriever_name","estimated_cost","total_estimated_stages"],"title":"ExplainRetrieverResponse","description":"Execution plan analysis for a retriever.\n\nProvides comprehensive diagnostics about retriever execution characteristics\nwithout actually running the query. Similar to MongoDB's explain plan or SQL's\nEXPLAIN command, this helps troubleshoot performance, estimate costs, and\nunderstand optimizer behavior.\n\nUse Cases:\n - Identify bottleneck stages before execution\n - Estimate costs for budget planning\n - Debug slow retrievers by analyzing stage efficiency\n - Understand optimizer transformations\n - Compare different retriever configurations\n - Troubleshoot accuracy issues via document flow analysis","examples":[{"bottleneck_stages":["semantic_search"],"description":"Simple retriever with optimization applied","estimated_cost":{"total_credits":0.51,"total_duration_ms":220.0},"execution_plan":[{"cache_likely":true,"estimated_cost_credits":0.0,"estimated_duration_ms":20.0,"estimated_efficiency":0.5,"estimated_input":10000,"estimated_output":5000,"optimization_notes":["Pushed down from stage 2"],"stage_index":0,"stage_name":"attribute_filter","stage_type":"filter","warnings":[]},{"cache_likely":false,"estimated_cost_credits":0.5,"estimated_duration_ms":200.0,"estimated_efficiency":0.02,"estimated_input":5000,"estimated_output":100,"optimization_notes":[],"stage_index":1,"stage_name":"semantic_search","stage_type":"filter","warnings":[]}],"optimization_applied":true,"optimization_details":{"decisions":[{"applied":true,"reason":"Moved attribute_filter before semantic_search","rule_type":"push_down_filters"}],"optimization_time_ms":8.2,"optimized_stage_count":2,"original_stage_count":3,"stage_reduction_pct":33.3},"optimization_level":"mvp","optimization_suggestions":[{"message":"Consider reducing limit to improve latency","stage":"semantic_search","type":"reduce_limit"}],"retriever_id":"ret_abc123","retriever_name":"product_search","total_estimated_stages":2},{"bottleneck_stages":["llm_quality_filter"],"description":"Complex retriever with bottleneck LLM stage","estimated_cost":{"total_credits":15.5,"total_duration_ms":8500.0},"execution_plan":[{"cache_likely":false,"estimated_cost_credits":0.5,"estimated_duration_ms":200.0,"estimated_efficiency":0.01,"estimated_input":10000,"estimated_output":100,"optimization_notes":[],"stage_index":0,"stage_name":"semantic_search","stage_type":"filter","warnings":[]},{"cache_likely":false,"estimated_cost_credits":15.0,"estimated_duration_ms":8000.0,"estimated_efficiency":0.1,"estimated_input":100,"estimated_output":10,"optimization_notes":[],"stage_index":1,"stage_name":"llm_quality_filter","stage_type":"filter","warnings":["High cost stage - consider reducing input count","Bottleneck stage - dominates execution time"]}],"optimization_applied":false,"optimization_level":"mvp","optimization_suggestions":[{"message":"Add attribute filter before this expensive LLM stage","stage":"llm_quality_filter","type":"add_filter"}],"retriever_id":"ret_xyz789","retriever_name":"advanced_search","total_estimated_stages":2}]},"ExplainStagePlan":{"properties":{"stage_index":{"type":"integer","minimum":0.0,"title":"Stage Index","description":"Zero-based position of this stage in the execution pipeline. Stages execute sequentially in this order. REQUIRED.","examples":[0,1,2]},"stage_name":{"type":"string","title":"Stage Name","description":"Human-readable name of this stage instance. Corresponds to the 'stage_name' field in your retriever configuration. Use this to map explain plan output back to your pipeline definition. REQUIRED.","examples":["initial_filter","semantic_search","rerank_by_relevance"]},"stage_type":{"type":"string","title":"Stage Type","description":"Stage type identifier indicating the category of operation. Common types: 'filter' (reduce documents), 'sort' (reorder), 'reduce' (aggregate), 'apply' (transform/enrich). REQUIRED.","examples":["filter","sort","reduce","apply"]},"estimated_input":{"type":"integer","minimum":0.0,"title":"Estimated Input","description":"Estimated number of documents entering this stage. This is the output count from the previous stage (or initial collection size). Used to project document flow through the pipeline. REQUIRED.","examples":[10000,5000,100]},"estimated_output":{"type":"integer","minimum":0.0,"title":"Estimated Output","description":"Estimated number of documents leaving this stage. For filter stages, this is typically less than estimated_input. For sort/reduce stages, this may be the same or less. REQUIRED.","examples":[5000,100,10]},"estimated_efficiency":{"type":"number","minimum":0.0,"title":"Estimated Efficiency","description":"Stage selectivity ratio (estimated_output / estimated_input). Values closer to 0 indicate aggressive filtering. Values closer to 1 indicate most documents pass through. Use this to identify stages that might be too restrictive or too permissive. REQUIRED.","examples":[0.5,0.02,0.9]},"estimated_cost_credits":{"type":"number","minimum":0.0,"title":"Estimated Cost Credits","description":"Estimated credit cost for executing this stage. Credits are consumed for inference (embeddings, LLM calls), vector searches, and other computational operations. Filter/sort stages typically have near-zero cost. REQUIRED.","examples":[0.0,0.5,15.0]},"estimated_duration_ms":{"type":"number","minimum":0.0,"title":"Estimated Duration Ms","description":"Estimated latency contribution of this stage in milliseconds. High values indicate potential bottlenecks. Sum across stages gives total estimated execution time. REQUIRED.","examples":[20.0,200.0,5000.0]},"cache_likely":{"type":"boolean","title":"Cache Likely","description":"Whether this stage is likely to hit cache based on recent execution history. True = cache hit likely (near-zero actual latency/cost). False = cache miss likely (full cost incurred). Use this to understand when queries will be fast vs slow. REQUIRED."},"optimization_notes":{"items":{"type":"string"},"type":"array","title":"Optimization Notes","description":"Human-readable notes about optimizations applied to this stage. Examples: 'Pushed down from stage 2', 'Merged with previous filter', 'Grouping pushed to database layer'. Empty if no optimizations were applied. OPTIONAL.","examples":[["Pushed down from stage 3 to reduce search scope"],["Merged with previous filter for efficiency"],[]]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Performance warnings or potential issues with this stage. Examples: 'High cost stage - consider reducing limit', 'Very low efficiency - may need filter tuning', 'LLM stage without prior filtering - expensive'. Empty if no warnings. OPTIONAL.","examples":[["High cost stage - consider reducing limit"],["Very low selectivity (0.001) - may indicate poor filter tuning"],[]]}},"type":"object","required":["stage_index","stage_name","stage_type","estimated_input","estimated_output","estimated_efficiency","estimated_cost_credits","estimated_duration_ms","cache_likely"],"title":"ExplainStagePlan","description":"Stage-level execution plan details for retriever explain endpoint.\n\nProvides detailed cost, performance, and optimization information for a single\nstage in the retriever pipeline. Use this to understand stage behavior, identify\nbottlenecks, and troubleshoot performance issues.\n\nThis is analogous to a single row in MongoDB's explain plan output, showing\nhow documents flow through the stage and what resources are consumed.","examples":[{"cache_likely":true,"description":"Fast filter stage with cache hit","estimated_cost_credits":0.0,"estimated_duration_ms":20.0,"estimated_efficiency":0.5,"estimated_input":10000,"estimated_output":5000,"optimization_notes":["Pushed down from stage 2"],"stage_index":0,"stage_name":"attribute_filter","stage_type":"filter","warnings":[]},{"cache_likely":false,"description":"Expensive semantic search stage","estimated_cost_credits":0.5,"estimated_duration_ms":200.0,"estimated_efficiency":0.02,"estimated_input":5000,"estimated_output":100,"optimization_notes":[],"stage_index":1,"stage_name":"semantic_search","stage_type":"filter","warnings":[]},{"cache_likely":false,"description":"Bottleneck LLM stage with warnings","estimated_cost_credits":15.0,"estimated_duration_ms":8000.0,"estimated_efficiency":0.1,"estimated_input":100,"estimated_output":10,"optimization_notes":[],"stage_index":2,"stage_name":"llm_quality_filter","stage_type":"filter","warnings":["High cost stage - consider reducing input count","Bottleneck stage - dominates execution time"]}]},"ExportFormat":{"type":"string","enum":["json","csv","parquet"],"title":"ExportFormat","description":"Supported export formats for collection data."},"ExternalLink":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Display name for the link","examples":["GitHub Repository","Blog Post","Documentation","Demo Video"]},"url":{"type":"string","maxLength":2048,"minLength":1,"title":"Url","description":"URL to the external resource","examples":["https://github.com/org/repo","https://blog.example.com/post","https://docs.example.com"]}},"type":"object","required":["name","url"],"title":"ExternalLink","description":"External resource link for a published retriever.\n\nUsed to link to related resources like GitHub repos, blog posts,\ndocumentation, or other relevant URLs displayed on the homepage.","examples":[{"name":"GitHub Repository","url":"https://github.com/mixpeek/video-search"},{"name":"Blog Post","url":"https://blog.mixpeek.com/building-semantic-search"}]},"ExtractorBreakdownResponse":{"properties":{"time_range":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Time range of the analysis"},"extractors":{"items":{"$ref":"#/components/schemas/ExtractorPerformance"},"type":"array","title":"Extractors","description":"Performance by extractor and stage"}},"type":"object","required":["time_range","extractors"],"title":"ExtractorBreakdownResponse","description":"Response for extractor performance breakdown."},"ExtractorDiscovery":{"properties":{"name":{"type":"string","title":"Name","description":"Feature extractor name (e.g., 'multimodal_extractor')"},"version":{"type":"string","title":"Version","description":"Feature extractor version (e.g., 'v1')"},"description":{"type":"string","title":"Description","description":"Human-readable description of what this extractor does"},"supported_modalities":{"items":{"type":"string"},"type":"array","title":"Supported Modalities","description":"List of supported input modalities (text, image, video, audio)"},"output_features":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Output Features","description":"List of features produced by this extractor"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"JSON Schema for extractor input parameters"},"example_usage":{"additionalProperties":true,"type":"object","title":"Example Usage","description":"Example manifest YAML snippet showing how to use this extractor"}},"type":"object","required":["name","version","description"],"title":"ExtractorDiscovery","description":"Feature extractor discovery information.\n\nProvides comprehensive information about a feature extractor\nfor agent-driven configuration and manifest generation.","examples":[{"description":"Extracts embeddings from text, images, and video frames","example_usage":{"collection":{"feature_extractor":{"input_mappings":{"content":"text"},"name":"multimodal_extractor"}},"namespace":{"feature_extractors":[{"name":"multimodal_extractor","version":"v1"}]}},"name":"multimodal_extractor","output_features":[{"dimensions":1024,"name":"embedding","type":"vector","uri":"multimodal_extractor.v1.embedding"}],"supported_modalities":["text","image","video"],"version":"v1"}]},"ExtractorJobInfo":{"properties":{"extractor_type":{"type":"string","title":"Extractor Type","description":"Feature extractor type (e.g., 'image_extractor', 'face_identity_extractor')","examples":["image_extractor","face_identity_extractor","video_extractor"]},"collection_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Collection Ids","description":"Collections processed by this extractor job","examples":[["col_abc123"],["col_def456","col_ghi789"]]},"ray_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Job Id","description":"Ray job ID for this extractor job","examples":["raysubmit_abc123"]},"celery_task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Celery Task Id","description":"Celery task ID that submitted this Ray job","examples":["celery_task_abc123"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"Current status of this extractor job","default":"PENDING","examples":["PENDING","IN_PROGRESS","COMPLETED","FAILED"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When this extractor job started processing"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When this extractor job finished processing"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms","description":"Processing duration in milliseconds"},"documents_written":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Written","description":"Number of documents written by this extractor job"},"errors":{"items":{"$ref":"#/components/schemas/BatchErrorDetail"},"type":"array","title":"Errors","description":"Detailed errors from this extractor job"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"OPTIONAL. Simple error message string for quick debugging. Set when the Ray job fails with error details from JobStatusMonitor. For detailed error information, see errors array.","examples":["Ray job FAILED","Timeout waiting for job completion"]}},"type":"object","required":["extractor_type"],"title":"ExtractorJobInfo","description":"Tracking information for a single feature extractor job within a tier.\n\nEach tier can have multiple extractor jobs running in parallel, one per unique\nfeature_extractor_type. This allows different extractors to have independent:\n- Resource requirements (GPUs, CPU, memory)\n- Status tracking and retry logic\n- Ray job IDs and Celery task IDs\n- Completion times and performance metrics\n\nExample:\n Tier 1 with collections using different extractors:\n - col_A: image_extractor\n - col_B: face_identity_extractor\n - col_C: image_extractor\n\n Creates 2 ExtractorJobInfo instances:\n 1. extractor_type=\"image_extractor\", collection_ids=[\"col_A\", \"col_C\"]\n 2. extractor_type=\"face_identity_extractor\", collection_ids=[\"col_B\"]\n\nLifecycle:\n 1. Created with status=PENDING when tier is scheduled\n 2. Updated to IN_PROGRESS when Ray job starts\n 3. Finalized to COMPLETED/FAILED when Ray job completes"},"ExtractorMetrics":{"properties":{"extractor_name":{"type":"string","title":"Extractor Name"},"version":{"type":"string","title":"Version"},"execution_count":{"type":"integer","title":"Execution Count"},"success_count":{"type":"integer","title":"Success Count"},"failure_count":{"type":"integer","title":"Failure Count"},"success_rate":{"type":"number","title":"Success Rate"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms"},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms"}},"type":"object","required":["extractor_name","version","execution_count","success_count","failure_count","success_rate","avg_latency_ms","p95_latency_ms","p99_latency_ms"],"title":"ExtractorMetrics","description":"Extractor performance metrics."},"ExtractorPerformance":{"properties":{"extractor_name":{"type":"string","title":"Extractor Name","description":"Name of the extractor"},"stage_name":{"type":"string","title":"Stage Name","description":"Name of the stage"},"execution_count":{"type":"integer","title":"Execution Count","description":"Number of executions"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"max_latency_ms":{"type":"number","title":"Max Latency Ms","description":"Maximum latency"}},"type":"object","required":["extractor_name","stage_name","execution_count","avg_latency_ms","p95_latency_ms","max_latency_ms"],"title":"ExtractorPerformance","description":"Performance breakdown by extractor."},"ExtractorPerformanceResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__collections__models__TimeRange"},"extractors":{"items":{"$ref":"#/components/schemas/ExtractorMetrics"},"type":"array","title":"Extractors"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"}},"type":"object","required":["collection_id","time_range","extractors"],"title":"ExtractorPerformanceResponse","description":"Extractor performance breakdown."},"ExtractorSource":{"type":"string","enum":["builtin","custom","community"],"title":"ExtractorSource","description":"The source/origin of a feature extractor.\n\nValues:\n BUILTIN: Core extractors shipped with Mixpeek (text, image, multimodal, etc.)\n CUSTOM: User-created extractors uploaded to their namespace (Enterprise only)\n COMMUNITY: Community-contributed extractors from the Mixpeek marketplace\n\nThis field helps API consumers understand:\n- What level of support/maintenance to expect\n- Whether the extractor is available to all users or namespace-specific\n- Licensing and attribution requirements"},"FaceIdentityExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"face_identity_extractor","title":"Extractor Type","description":"Discriminator field for parameter type identification. Must be 'face_identity_extractor'.","default":"face_identity_extractor"},"detection_model":{"type":"string","enum":["scrfd_500m","scrfd_2.5g","scrfd_10g"],"title":"Detection Model","description":"SCRFD model for face detection. 'scrfd_500m': Fastest (2-3ms). 'scrfd_2.5g': Balanced (5-7ms), recommended. 'scrfd_10g': Highest accuracy (10-15ms).","default":"scrfd_2.5g"},"min_face_size":{"type":"integer","maximum":200.0,"minimum":10.0,"title":"Min Face Size","description":"Minimum face size in pixels to detect. 20px: Balanced. 40px: Higher quality. 10px: Maximum recall.","default":20},"detection_threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Detection Threshold","description":"Confidence threshold for face detection (0.0-1.0).","default":0.5},"max_faces_per_image":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Faces Per Image","description":"Maximum number of faces to process per image. None: Process all."},"normalize_embeddings":{"type":"boolean","title":"Normalize Embeddings","description":"L2-normalize embeddings to unit vectors (recommended).","default":true},"enable_quality_scoring":{"type":"boolean","title":"Enable Quality Scoring","description":"Compute quality scores (blur, size, landmarks). Adds ~5ms per face.","default":true},"quality_threshold":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Quality Threshold","description":"Minimum quality score to index faces. None: Index all faces. 0.5: Moderate filtering. 0.7: High quality only."},"max_video_length":{"type":"integer","maximum":300.0,"minimum":1.0,"title":"Max Video Length","description":"Maximum video length in seconds. 60: Default. 10: Recommended for retrieval. 300: Maximum (extraction only).","default":60},"video_sampling_fps":{"anyOf":[{"type":"number","maximum":60.0,"minimum":0.1},{"type":"null"}],"title":"Video Sampling Fps","description":"Frames per second to sample from video. 1.0: One frame per second (recommended).","default":1.0},"video_deduplication":{"type":"boolean","title":"Video Deduplication","description":"Remove duplicate faces across video frames (extraction only). Reduces 90-95% redundancy. NOT used in retrieval.","default":true},"video_deduplication_threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Video Deduplication Threshold","description":"Cosine similarity threshold for deduplication. 0.8: Conservative (default).","default":0.8},"output_mode":{"type":"string","enum":["per_face","per_image"],"title":"Output Mode","description":"'per_face': One document per face (recommended). 'per_image': One doc per image with faces array.","default":"per_face"},"include_face_crops":{"type":"boolean","title":"Include Face Crops","description":"Include aligned 112Ɨ112 face crops as base64. Adds ~5KB per face.","default":false},"include_source_frame_thumbnail":{"type":"boolean","title":"Include Source Frame Thumbnail","description":"Include resized source frame/image as base64 thumbnail (~15-30KB per face). Used for display with bounding box overlay.","default":false},"store_detection_metadata":{"type":"boolean","title":"Store Detection Metadata","description":"Store bbox, landmarks, detection scores. Recommended for debugging.","default":true}},"type":"object","title":"FaceIdentityExtractorParams","description":"Parameters for the Face Identity Extractor.\n\nThe Face Identity Extractor processes images or video frames to detect, align,\nand embed faces using production-grade SOTA models (SCRFD + ArcFace).\n\nCore Pipeline:\n1. SCRFD Detection ā†’ Bounding boxes + 5 landmarks\n2. 5-Point Affine Alignment ā†’ 112Ɨ112 canonical face\n3. ArcFace Embedding ā†’ 512-d L2-normalized vector\n4. Optional Quality Scoring ā†’ Filter low-quality faces\n\nUse Cases:\n - Face verification (1:1 matching)\n - Face identification (1:N search)\n - Face clustering (group photos by person)\n - Duplicate face detection","examples":[{"description":"Employee verification (high quality, 1:1 matching)","detection_model":"scrfd_2.5g","detection_threshold":0.7,"enable_quality_scoring":true,"extractor_type":"face_identity_extractor","max_faces_per_image":1,"min_face_size":40,"normalize_embeddings":true,"output_mode":"per_face","quality_threshold":0.5,"use_case":"Corporate access control, employee ID photos for badge matching"},{"description":"Photo library organization (multiple faces)","detection_model":"scrfd_2.5g","detection_threshold":0.6,"enable_quality_scoring":true,"extractor_type":"face_identity_extractor","min_face_size":30,"output_mode":"per_face","store_detection_metadata":true,"use_case":"Personal photo management: group photos by person"}]},"FailedObjectError":{"properties":{"object_index":{"type":"integer","title":"Object Index","description":"0-based index of the failed object in the batch request"},"error":{"type":"string","title":"Error","description":"Error message describing why the object failed"},"error_type":{"type":"string","title":"Error Type","description":"Type of error (e.g., 'ValidationError', 'URLValidationError')"}},"type":"object","required":["object_index","error","error_type"],"title":"FailedObjectError","description":"Error details for a failed object in a batch.","examples":[{"error":"Schema validation failed: Missing required field 'title'","error_type":"ValidationError","object_index":15},{"error":"URL validation failed: URL returned status 404","error_type":"URLValidationError","object_index":42}]},"FailureMetric":{"properties":{"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"execution_id":{"type":"string","title":"Execution Id"},"error_message":{"type":"string","title":"Error Message"},"error_type":{"type":"string","title":"Error Type"}},"type":"object","required":["timestamp","execution_id","error_message","error_type"],"title":"FailureMetric","description":"Cluster failure metrics."},"FeatureAddress":{"properties":{"scheme":{"type":"string","title":"Scheme","default":"mixpeek"},"extractor":{"type":"string","title":"Extractor"},"version":{"type":"string","title":"Version"},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output"}},"type":"object","required":["extractor","version"],"title":"FeatureAddress","description":"Canonical feature address: mixpeek://{extractor}@{version}/{output}.\n\nThe output segment is the inference_name (embedding model identifier), which enables\ncross-extractor compatibility checking. Two feature URIs with the same inference_name\nin the output segment produce compatible embeddings that can be compared/fused.\n\nFormat examples:\n - mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\n - mixpeek://multimodal_extractor@v1/multilingual_e5_large_instruct_v1 (compatible with above!)\n - mixpeek://image_extractor@v1/google_siglip_base_v1 (different model = incompatible)\n\nShort form without the output segment is allowed only if the extractor has\na single vector output."},"FeatureExtractorResponseModel":{"properties":{"feature_extractor_name":{"type":"string","title":"Feature Extractor Name"},"version":{"type":"string","title":"Version"},"feature_extractor_id":{"type":"string","title":"Feature Extractor Id"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"source":{"$ref":"#/components/schemas/ExtractorSource","description":"The origin/source of this extractor: 'builtin' (shipped with Mixpeek), 'custom' (user-created), or 'community' (marketplace).","default":"builtin"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"output_schema":{"additionalProperties":true,"type":"object","title":"Output Schema"},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema"},"supported_input_types":{"items":{"type":"string"},"type":"array","title":"Supported Input Types"},"max_inputs":{"additionalProperties":{"type":"integer"},"type":"object","title":"Max Inputs"},"default_parameters":{"additionalProperties":true,"type":"object","title":"Default Parameters"},"costs":{"anyOf":[{"$ref":"#/components/schemas/CostsInfo"},{"type":"null"}],"description":"Credit cost information for this extractor"},"required_vector_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/VectorIndexDefinition"},"type":"array"},{"type":"null"}],"title":"Required Vector Indexes"},"required_payload_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayloadIndexConfig-Output"},"type":"array"},{"type":"null"}],"title":"Required Payload Indexes"},"position_fields":{"items":{"type":"string"},"type":"array","title":"Position Fields","description":"Output fields that uniquely identify each document within a source object. Enables idempotent reprocessing: rerunning a batch produces the same document IDs, so existing documents are updated instead of creating duplicates. Works with bucket `unique_key` to enable fully deterministic document IDs. Empty list means single-output extractor (one document per source). Read-only (set by extractor).","examples":[["start_time","end_time"],["chunk_index"],[]]}},"type":"object","required":["feature_extractor_name","version","feature_extractor_id","description","icon","input_schema","output_schema","parameter_schema","supported_input_types","max_inputs","default_parameters","required_vector_indexes","required_payload_indexes"],"title":"FeatureExtractorResponseModel","description":"Feature extractor response model for API responses."},"FeatureModel":{"properties":{"feature_extractor_id":{"type":"string","title":"Feature Extractor Id","description":"ID of the feature extractor that produced this response"},"payload":{"additionalProperties":true,"type":"object","title":"Payload","description":"Metadata of the feature"},"vectors":{"anyOf":[{"$ref":"#/components/schemas/DenseVector"},{"$ref":"#/components/schemas/SparseVector"},{"$ref":"#/components/schemas/MultiDenseVector"},{"$ref":"#/components/schemas/NamedDenseVectors"},{"type":"null"}],"title":"Vectors","description":"Vector representation of the feature. Can be any supported vector type."}},"additionalProperties":true,"type":"object","required":["feature_extractor_id"],"title":"FeatureModel","description":"Response from a feature extractor."},"FeaturedGalleryConfig-Input":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Whether the featured gallery is shown","default":true},"title":{"type":"string","title":"Title","description":"Gallery section title","default":"Featured"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Internal retriever ID (defaults to first tab's retriever)"},"public_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Name","description":"Marketplace catalog public_name for gallery execution"},"default_inputs":{"additionalProperties":true,"type":"object","title":"Default Inputs","description":"Default inputs to auto-execute when page loads"},"layout":{"$ref":"#/components/schemas/LayoutConfig","description":"Layout configuration for gallery results"},"field_config":{"additionalProperties":{"$ref":"#/components/schemas/FieldConfig"},"type":"object","title":"Field Config","description":"Field display configuration for gallery results"}},"type":"object","title":"FeaturedGalleryConfig","description":"Configuration for the featured gallery section."},"FeaturedGalleryConfig-Output":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Whether the featured gallery is shown","default":true},"title":{"type":"string","title":"Title","description":"Gallery section title","default":"Featured"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Internal retriever ID (defaults to first tab's retriever)"},"public_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Name","description":"Marketplace catalog public_name for gallery execution"},"default_inputs":{"additionalProperties":true,"type":"object","title":"Default Inputs","description":"Default inputs to auto-execute when page loads"},"layout":{"$ref":"#/components/schemas/LayoutConfig","description":"Layout configuration for gallery results"},"field_config":{"additionalProperties":{"$ref":"#/components/schemas/FieldConfig"},"type":"object","title":"Field Config","description":"Field display configuration for gallery results"}},"type":"object","title":"FeaturedGalleryConfig","description":"Configuration for the featured gallery section."},"FieldConfig":{"properties":{"format":{"$ref":"#/components/schemas/FieldFormatType","description":"Format type for this field (text, image, date, number, etc.)"},"format_options":{"$ref":"#/components/schemas/FieldFormatOptions","description":"Format-specific display options"}},"type":"object","required":["format"],"title":"FieldConfig","description":"Configuration for how to display a specific field in results.","examples":[{"format":"text","format_options":{"label":"Title","truncate_chars":60}},{"format":"image","format_options":{"aspect_ratio":"16/9","height":300,"lazy_load":true,"width":400}},{"format":"date","format_options":{"date_format":"relative","label":"Posted"}},{"format":"number","format_options":{"decimals":2,"label":"Price","prefix":"$"}}]},"FieldFormatOptions":{"properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Display label for this field","examples":["Title","Price","Posted Date"]},"show_empty":{"type":"boolean","title":"Show Empty","description":"Whether to show the field if value is empty/null","default":true},"truncate_chars":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Truncate Chars","description":"Maximum characters before truncation (for text fields)","examples":[60,120,200]},"width":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Width","description":"Image width in pixels","examples":[400,800]},"height":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Height","description":"Image height in pixels","examples":[300,600]},"lazy_load":{"type":"boolean","title":"Lazy Load","description":"Enable lazy loading for images (default: true)","default":true},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio","description":"Aspect ratio for image container","examples":["16/9","4/3","1/1"]},"object_fit":{"type":"string","title":"Object Fit","description":"CSS object-fit property for images","default":"cover","examples":["cover","contain","fill"]},"date_format":{"type":"string","title":"Date Format","description":"Date format type: 'iso', 'relative', or custom format string","default":"relative","examples":["relative","iso","MMM DD, YYYY"]},"decimals":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Decimals","description":"Number of decimal places","examples":[0,1,2]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prefix","description":"Prefix for number display","examples":["$","ā‚¬","#"]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suffix","description":"Suffix for number display","examples":["%","k","M"]},"open_in_new_tab":{"type":"boolean","title":"Open In New Tab","description":"Open URLs in new tab (default: true)","default":true},"show_domain":{"type":"boolean","title":"Show Domain","description":"Show domain instead of full URL","default":false},"true_label":{"type":"string","title":"True Label","description":"Label for true values","default":"Yes"},"false_label":{"type":"string","title":"False Label","description":"Label for false values","default":"No"},"separator":{"type":"string","title":"Separator","description":"Separator for array items (default: ', ')","default":", "},"max_items":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Items","description":"Maximum array items to display"}},"type":"object","title":"FieldFormatOptions","description":"Format-specific options for field display.\n\nDifferent format types support different options:\n- text: label, truncate_chars, show_empty\n- image: width, height, lazy_load, aspect_ratio, object_fit\n- date: label, date_format (iso, relative, custom)\n- number: label, decimals, prefix, suffix, show_empty\n- url: label, open_in_new_tab, show_domain\n- boolean: label, true_label, false_label\n- array: label, separator, max_items","examples":[{"label":"Title","show_empty":false,"truncate_chars":60},{"aspect_ratio":"16/9","height":300,"label":"Thumbnail","lazy_load":true,"object_fit":"cover","width":400},{"date_format":"relative","label":"Posted"},{"decimals":2,"label":"Price","prefix":"$"}]},"FieldFormatType":{"type":"string","enum":["text","image","date","number","url","boolean","array","object"],"title":"FieldFormatType","description":"Supported field format types for result display."},"FieldMappingEntry":{"properties":{"target_type":{"type":"string","const":"field","title":"Target Type","description":"Target type. Must be 'field' for regular schema fields.","default":"field"},"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 value. Options: tag, metadata, filename_regex, column, drive_property, folder_path, constant. The 'file' source is not valid for field mappings (use blob instead).","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"}}},"transform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transform","description":"Optional transformation to apply to the extracted value. Supported transforms: 'lowercase' - convert to lowercase, 'uppercase' - convert to uppercase, 'trim' - remove leading/trailing whitespace, 'json_parse' - parse JSON string to object/array. Transforms are applied after extraction, before storage.","examples":["lowercase","uppercase","trim","json_parse"]},"required":{"type":"boolean","title":"Required","description":"If True, the sync will fail if this field cannot be extracted. If False (default), missing values result in the field being omitted. Use required=True for critical fields that must be present.","default":false}},"type":"object","required":["source"],"title":"FieldMappingEntry","description":"Maps a source value to a bucket schema field.\n\nUsed for mapping metadata, tags, columns, or extracted values to\nregular fields in the bucket schema (strings, numbers, arrays, etc.).\nDoes NOT handle file content - use BlobMappingEntry for that.\n\nExample: Map S3 tag \"category\" to bucket field \"content_category\"\n {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"tag\", \"key\": \"category\"}\n }\n\nExample: Map folder name to \"department\" with lowercase transform\n {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"folder_path\", \"segment\": 0},\n \"transform\": \"lowercase\"\n }\n\nExample: Map filename regex capture to \"date\" field\n {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"filename_regex\", \"pattern\": \"^(\\d{4}-\\d{2}-\\d{2})\"},\n \"required\": true\n }\n\nAttributes:\n target_type: Must be \"field\" for schema field mappings\n source: The source extractor defining where to get the value\n transform: Optional transformation to apply (lowercase, uppercase, trim)\n required: Whether missing values should fail the sync"},"FieldPassthrough":{"properties":{"source_path":{"type":"string","title":"Source Path","description":"REQUIRED. Path to the source field to copy. Simple fields: Use field name directly (e.g., 'title', 'campaign_id'). Nested fields: Use dot notation (e.g., 'metadata.author', 'config.model.version'). The field must exist in the source bucket schema or upstream collection schema. Without target_path, nested fields are flattened: 'metadata.author' becomes 'author' in output.","examples":["title","campaign_id","metadata.author","config.model_version","category"]},"target_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Path","description":"OPTIONAL. Target field name in output document. If NOT PROVIDED: Uses source_path name (or last component for nested paths). - 'title' ā†’ 'title' - 'metadata.author' ā†’ 'author' If PROVIDED: Uses this exact name in output. - source_path='doc_title', target_path='title' ā†’ 'title' - source_path='metadata.author', target_path='contributor' ā†’ 'contributor' Use cases: - Rename fields for cleaner API schemas - Avoid name conflicts with extractor outputs - Standardize field names across different sources Constraints: - Must not conflict with system fields (document_id, collection_id, etc.) - Must not conflict with extractor output fields - Must be a valid field name (alphanumeric, underscores, hyphens)","examples":["title","author","campaign_name","product_id","user_email"]},"default":{"anyOf":[{},{"type":"null"}],"title":"Default","description":"OPTIONAL. Default value if source field doesn't exist or is None. If NOT PROVIDED and field missing: Field is omitted from output document. If PROVIDED and field missing: Field is included with this default value. Type should match expected field type (string, int, list, dict, etc.).","examples":["Unknown","N/A",0,[],{},false]},"required":{"type":"boolean","title":"Required","description":"OPTIONAL. Whether this field MUST exist in source. If True and field missing: Raises validation error, processing fails. If False and field missing: Field omitted (or default used if provided). Use True for: Critical identifiers, required business fields. Use False for: Optional metadata, nice-to-have fields. Default: False (field is optional).","default":false}},"type":"object","required":["source_path"],"title":"FieldPassthrough","description":"Configuration for passing fields from source to output documents.\n\nSimple field passthrough: specify which fields to copy from source (bucket object\nor upstream collection document) to the output documents alongside extractor outputs.\n\nUse Cases:\n - Preserve identifiers: campaign_id, product_sku, user_id\n - Keep metadata: category, tags, author, timestamp\n - Maintain business context: priority, status, region\n - Extract nested values: metadata.author, config.model_version\n - Rename fields for cleaner schemas: doc_title ā†’ title\n\nField Selection:\n - WITHOUT field_passthrough: Only extractor outputs appear in documents\n - WITH field_passthrough: Specified fields + extractor outputs\n - WITH include_all_source_fields=True: All source fields + extractor outputs\n\nField Naming:\n - WITHOUT target_path: Output uses source name (or last component for nested)\n - \"title\" ā†’ \"title\"\n - \"metadata.author\" ā†’ \"author\"\n - WITH target_path: Output uses specified name\n - source_path=\"doc_title\", target_path=\"title\" ā†’ \"title\"\n - source_path=\"metadata.author\", target_path=\"contributor\" ā†’ \"contributor\"\n\nRequirements:\n - source_path is REQUIRED - specifies which field to copy (supports dot notation)\n - target_path is OPTIONAL - rename field in output (default: auto-derived name)\n - default is OPTIONAL - provides fallback if field missing (default: omit field)\n - required is OPTIONAL - errors if field missing (default: false, omit field)","examples":[{"description":"Simple field passthrough","required":true,"source_path":"title"},{"default":"uncategorized","description":"Field with default value","source_path":"category"},{"description":"Field renaming for cleaner schema","source_path":"doc_title","target_path":"title"},{"description":"Nested field extraction with custom name","source_path":"metadata.author","target_path":"contributor"},{"description":"Required field with renaming","required":true,"source_path":"campaign_id","target_path":"campaign"},{"default":"normal","description":"Optional field with default and renaming","required":false,"source_path":"metadata.priority","target_path":"priority"}]},"FieldPerformanceMetrics":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Metadata field name"},"usage_count":{"type":"integer","title":"Usage Count","description":"Number of times field was queried"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency when field is used"},"p50_latency_ms":{"type":"number","title":"P50 Latency Ms","description":"50th percentile latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms","description":"99th percentile latency"},"max_latency_ms":{"type":"number","title":"Max Latency Ms","description":"Maximum latency observed"},"index_priority_score":{"type":"number","title":"Index Priority Score","description":"Priority score for indexing (usage_count * avg_latency)"}},"type":"object","required":["field_name","usage_count","avg_latency_ms","p50_latency_ms","p95_latency_ms","p99_latency_ms","max_latency_ms","index_priority_score"],"title":"FieldPerformanceMetrics","description":"Performance correlation metrics for a field."},"FieldPerformanceResponse":{"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"},"fields":{"items":{"$ref":"#/components/schemas/FieldPerformanceMetrics"},"type":"array","title":"Fields","description":"Field performance metrics"},"total_fields":{"type":"integer","title":"Total Fields","description":"Total fields analyzed"}},"type":"object","required":["namespace_id","time_range_days","fields","total_fields"],"title":"FieldPerformanceResponse","description":"Response for field performance correlation endpoint."},"FieldQueryMetrics":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Metadata field name"},"query_count":{"type":"integer","title":"Query Count","description":"Number of queries using this field"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average query latency in milliseconds"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency in milliseconds"}},"type":"object","required":["field_name","query_count","avg_latency_ms","p95_latency_ms"],"title":"FieldQueryMetrics","description":"Metrics for a metadata field's query usage."},"FieldUsageResponse":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace being analyzed"},"period":{"type":"string","title":"Period","description":"Analysis period (24h, 7d, 30d)"},"fields":{"items":{"$ref":"#/components/schemas/FieldUsageStat"},"type":"array","title":"Fields","description":"Field usage statistics"},"total_fields":{"type":"integer","title":"Total Fields","description":"Total number of fields found"},"indexed_fields":{"type":"integer","title":"Indexed Fields","description":"Number of indexed fields"},"unindexed_fields":{"type":"integer","title":"Unindexed Fields","description":"Number of unindexed fields"}},"type":"object","required":["namespace_id","period","fields","total_fields","indexed_fields","unindexed_fields"],"title":"FieldUsageResponse","description":"Response containing field usage statistics."},"FieldUsageStat":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Field name"},"query_count":{"type":"integer","title":"Query Count","description":"Number of queries using this field"},"unique_queries":{"type":"integer","title":"Unique Queries","description":"Number of unique query executions"},"is_indexed":{"type":"boolean","title":"Is Indexed","description":"Whether field has an index"},"is_protected":{"type":"boolean","title":"Is Protected","description":"Whether field is system-protected"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average query latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"first_seen":{"type":"string","format":"date-time","title":"First Seen","description":"First usage timestamp"},"last_seen":{"type":"string","format":"date-time","title":"Last Seen","description":"Most recent usage timestamp"}},"type":"object","required":["field_name","query_count","unique_queries","is_indexed","is_protected","avg_latency_ms","p95_latency_ms","first_seen","last_seen"],"title":"FieldUsageStat","description":"Usage statistics for a filtered field."},"FileFilters":{"properties":{"include_patterns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include Patterns","description":"Glob patterns to include (e.g. ['*.mp4', '*.mov'])."},"exclude_patterns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Exclude Patterns","description":"Glob patterns to exclude (e.g. ['*/drafts/*', '*_temp.*'])."},"min_size_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Min Size Bytes","description":"Minimum file size (bytes). Files smaller are skipped."},"max_size_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Size Bytes","description":"Maximum file size (bytes). Files larger are skipped."},"modified_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Modified After","description":"Only sync files modified after this timestamp."},"modified_before":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Modified Before","description":"Only sync files modified before this timestamp."},"mime_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Mime Types","description":"Optional list of MIME types to include."}},"type":"object","title":"FileFilters","description":"Filter rules controlling which files are synced from storage providers.\n\nAll filters are optional and combined with AND logic.\nFiles must pass ALL specified filters to be synced.\n\n**Pattern Matching:** Uses glob patterns (*, ?, [abc], etc.)\n**Size Filtering:** Bytes-based, inclusive bounds\n**Time Filtering:** ISO 8601 datetime, based on provider's modified timestamp"},"FileSource":{"properties":{"type":{"type":"string","const":"file","title":"Type","description":"Source type identifier. Must be 'file' for the synced file itself.","default":"file"}},"type":"object","title":"FileSource","description":"Use the synced file itself as the source (for blob mappings).\n\nThis is the primary source for blob-type mappings where the synced file\ncontent becomes the blob. The mime_type is automatically detected from\nthe file unless explicitly overridden in the BlobMappingEntry.\n\nProvider Compatibility: All providers (works on any synced file)\n\nExample usage:\n {\"type\": \"file\"} -> The synced file becomes the blob content\n\nThis source type has no additional configuration - it simply indicates\nthat the synced file content should be used as the blob data.\n\nAttributes:\n type: Must be \"file\" to identify this source type"},"FilenameRegexSource":{"properties":{"type":{"type":"string","const":"filename_regex","title":"Type","description":"Source type identifier. Must be 'filename_regex' for regex extraction.","default":"filename_regex"},"pattern":{"type":"string","minLength":1,"title":"Pattern","description":"Python regex pattern with exactly one capture group. The captured group becomes the extracted value. Pattern is applied to the filename only (not full path). Use non-capturing groups (?:...) for grouping without capturing. Remember to escape backslashes in JSON (\\\\d instead of \\d).","examples":["^(\\w+)_","_(\\d+)_","\\.(\\w+)$","^(\\d{4}-\\d{2}-\\d{2})"]},"default":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default","description":"Default value if regex doesn't match the filename. If None and regex doesn't match, the field is omitted from the object. Useful for ensuring a field always has a value.","examples":["unknown","default","unclassified"]}},"type":"object","required":["pattern"],"title":"FilenameRegexSource","description":"Extract value from filename using a regex pattern with capture groups.\n\nUseful when metadata is encoded in filenames following a naming convention.\nThe regex must contain exactly one capture group to extract the value.\n\nProvider Compatibility: All providers (works on any filename)\n\nExample filenames and patterns:\n - \"marketing_Q4_2024_final.mp4\" with pattern \"^(\\w+)_Q\\d+_\" -> \"marketing\"\n - \"user_12345_avatar.jpg\" with pattern \"user_(\\d+)_\" -> \"12345\"\n - \"2024-01-15_meeting_notes.pdf\" with pattern \"^(\\d{4}-\\d{2}-\\d{2})\" -> \"2024-01-15\"\n - \"IMG_20240115_143022.jpg\" with pattern \"IMG_(\\d{8})_\" -> \"20240115\"\n\nNote: Use raw strings in Python or double-escape backslashes in JSON.\n\nAttributes:\n type: Must be \"filename_regex\" to identify this source type\n pattern: Python regex with exactly one capture group\n default: Optional default value if regex doesn't match"},"FilterCondition":{"properties":{"field":{"type":"string","title":"Field","description":"Field name to filter on"},"operator":{"$ref":"#/components/schemas/FilterOperator","description":"Comparison operator","default":"eq"},"value":{"anyOf":[{"$ref":"#/components/schemas/DynamicValue"},{}],"title":"Value","description":"Value to compare against"}},"type":"object","required":["field","value"],"title":"FilterCondition","description":"Represents a single filter condition.\n\nAttributes:\n field: The field to filter on\n operator: The comparison operator\n value: The value to compare against"},"FilterOperator":{"type":"string","enum":["eq","ne","gt","lt","gte","lte","in","nin","contains","starts_with","ends_with","regex","exists","is_null","text"],"title":"FilterOperator","description":"Supported filter operators across database implementations."},"FlatTaxonomyConfig-Input":{"properties":{"taxonomy_type":{"type":"string","const":"flat","title":"Taxonomy Type","description":"Discriminator identifying this as a flat taxonomy.","default":"flat"},"retriever_id":{"type":"string","title":"Retriever Id","description":"The retriever to use for matching against the source collection."},"input_mappings":{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array","title":"Input Mappings","description":"Input mappings defining how to construct retriever inputs."},"source_collection":{"$ref":"#/components/schemas/SourceCollection-Input","description":"The single source collection for this flat taxonomy."},"step_analytics":{"anyOf":[{"$ref":"#/components/schemas/StepAnalyticsConfig-Input"},{"type":"null"}],"description":"Optional configuration for step transition analytics. Enables tracking how documents progress through taxonomy labels over time (e.g., email thread progression from 'inquiry' to 'closed_won'). If not provided, only basic assignment events are logged."}},"type":"object","required":["retriever_id","input_mappings","source_collection"],"title":"FlatTaxonomyConfig","description":"Configuration for a *flat* taxonomy - single source collection with one retriever.","examples":[{"input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1","enrichment_fields":[{"field_path":"metadata.tags","merge_mode":"append"}]},"taxonomy_type":"flat"}]},"FlatTaxonomyConfig-Output":{"properties":{"taxonomy_type":{"type":"string","const":"flat","title":"Taxonomy Type","description":"Discriminator identifying this as a flat taxonomy.","default":"flat"},"retriever_id":{"type":"string","title":"Retriever Id","description":"The retriever to use for matching against the source collection."},"input_mappings":{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array","title":"Input Mappings","description":"Input mappings defining how to construct retriever inputs."},"source_collection":{"$ref":"#/components/schemas/SourceCollection-Output","description":"The single source collection for this flat taxonomy."},"step_analytics":{"anyOf":[{"$ref":"#/components/schemas/StepAnalyticsConfig-Output"},{"type":"null"}],"description":"Optional configuration for step transition analytics. Enables tracking how documents progress through taxonomy labels over time (e.g., email thread progression from 'inquiry' to 'closed_won'). If not provided, only basic assignment events are logged."}},"type":"object","required":["retriever_id","input_mappings","source_collection"],"title":"FlatTaxonomyConfig","description":"Configuration for a *flat* taxonomy - single source collection with one retriever.","examples":[{"input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1","enrichment_fields":[{"field_path":"metadata.tags","merge_mode":"append"}]},"taxonomy_type":"flat"}]},"FloatIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"float"}},"type":"object","title":"FloatIndexParams","description":"Configuration for float index."},"FolderItem":{"properties":{"id":{"type":"string","title":"Id","description":"REQUIRED. Folder ID in Google Drive. Use this ID when configuring sync operations. Format: Google Drive folder identifier (e.g., '0AH-Xabc123').","examples":["0AH-Xabc123","1ABCdef456GHI"]},"name":{"type":"string","title":"Name","description":"REQUIRED. Display name of the folder. Human-readable name shown in the Google Drive UI.","examples":["Marketing","2024 Campaigns","Assets"]},"path":{"type":"string","title":"Path","description":"REQUIRED. Full path from root to this folder. Format: '/' for root, '/FolderName' for first level, '/Parent/Child' for nested folders.","examples":["/","/Marketing","/Marketing/2024 Campaigns"]},"mime_type":{"type":"string","title":"Mime Type","description":"REQUIRED. MIME type identifier for folders. Always 'application/vnd.google-apps.folder' for folders.","examples":["application/vnd.google-apps.folder"]}},"type":"object","required":["id","name","path","mime_type"],"title":"FolderItem","description":"Represents a folder in Google Drive for folder selection in sync configuration.\n\nUsed by the list folders endpoint to help users browse and select folders\nfor sync operations. Only available for Google Drive connections.","examples":[{"description":"Root folder","id":"root","mime_type":"application/vnd.google-apps.folder","name":"My Drive","path":"/"},{"description":"Nested folder","id":"0AH-Xabc123","mime_type":"application/vnd.google-apps.folder","name":"Marketing","path":"/Marketing"}]},"FolderPathSource":{"properties":{"type":{"type":"string","const":"folder_path","title":"Type","description":"Source type identifier. Must be 'folder_path' for path extraction.","default":"folder_path"},"segment":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Segment","description":"Extract a specific path segment by index. 0 = first segment (root folder), 1 = second segment, etc. -1 = last segment (immediate parent), -2 = second to last, etc. If None and full_path is False, extracts the immediate parent folder.","examples":[0,1,2,-1,-2]},"full_path":{"type":"boolean","title":"Full Path","description":"If True, extracts the complete folder path (joined with '/'). If False, extracts only the segment specified or immediate parent. Does not include the filename.","default":false}},"type":"object","title":"FolderPathSource","description":"Extract value from the folder path structure.\n\nUseful for deriving categories or metadata from folder organization.\nCan extract the full path, a specific segment, or the immediate parent.\n\nProvider Compatibility: All providers with folder/prefix structure\n\nExample folder structure: /Marketing/Campaigns/Q4-2024/videos/\n - segment=0 -> \"Marketing\"\n - segment=1 -> \"Campaigns\"\n - segment=2 -> \"Q4-2024\"\n - segment=-1 -> \"videos\" (last segment)\n - full_path=True -> \"Marketing/Campaigns/Q4-2024/videos\"\n - Neither (default) -> \"videos\" (immediate parent)\n\nUse Cases:\n - Derive category from top-level folder\n - Extract project name from folder structure\n - Preserve full path for hierarchical organization\n\nAttributes:\n type: Must be \"folder_path\" to identify this source type\n segment: Index of path segment to extract (0-based, negative for reverse)\n full_path: Whether to extract complete path"},"GaussianMixtureParams":{"properties":{"n_components":{"type":"integer","minimum":1.0,"title":"N Components","description":"Number of mixture components","default":1},"covariance_type":{"type":"string","title":"Covariance Type","description":"Type of covariance parameters ('full', 'tied', 'diag', 'spherical')","default":"full"},"tol":{"type":"number","exclusiveMinimum":0.0,"title":"Tol","description":"Convergence threshold","default":0.001},"reg_covar":{"type":"number","minimum":0.0,"title":"Reg Covar","description":"Regularization added to the diagonal of covariance","default":1e-06},"max_iter":{"type":"integer","minimum":1.0,"title":"Max Iter","description":"Maximum number of EM iterations","default":100},"n_init":{"type":"integer","minimum":1.0,"title":"N Init","description":"Number of initializations to perform","default":1},"init_params":{"type":"string","title":"Init Params","description":"Method used to initialize weights, means and covariances ('kmeans' or 'random')","default":"kmeans"},"weights_init":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Weights Init","description":"Initial weights"},"means_init":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Means Init","description":"Initial means"},"precisions_init":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Precisions Init","description":"Initial precisions"},"random_state":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Random State","description":"Random seed for reproducibility","default":42},"warm_start":{"type":"boolean","title":"Warm Start","description":"If True, use the solution of the last fit as initialization","default":false},"verbose":{"type":"integer","minimum":0.0,"title":"Verbose","description":"Enable verbose output","default":0},"verbose_interval":{"type":"integer","minimum":1.0,"title":"Verbose Interval","description":"Number of iterations between each verbose message","default":10}},"type":"object","title":"GaussianMixtureParams","description":"Parameters for Gaussian Mixture Model clustering."},"GenerationConfig":{"properties":{"candidate_count":{"type":"integer","title":"Candidate Count","description":"Number of candidate responses to generate for video description.","default":1},"max_output_tokens":{"type":"integer","title":"Max Output Tokens","description":"Maximum number of tokens for the generated video description.","default":1024},"temperature":{"type":"number","title":"Temperature","description":"Controls randomness for video description generation. Higher is more random.","default":0.7},"top_p":{"type":"number","title":"Top P","description":"Nucleus sampling (top-p) for video description generation.","default":0.8},"response_mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Mime Type","description":"MIME type for response (e.g., 'application/json')"},"response_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Schema","description":"JSON schema for structured output"}},"type":"object","title":"GenerationConfig","description":"Configuration for generative models."},"GenericDeleteResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Successfully deleted"},"success":{"type":"boolean","title":"Success","default":true}},"type":"object","title":"GenericDeleteResponse","description":"GenericDeleteResponse."},"GenericSuccessResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Successfully completed"},"success":{"type":"boolean","title":"Success","default":true}},"type":"object","title":"GenericSuccessResponse","description":"GenericSuccessResponse."},"GeoIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"geo"}},"type":"object","title":"GeoIndexParams","description":"Configuration for geo index."},"GetHistoryResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session identifier"},"messages":{"items":{"$ref":"#/components/schemas/MessageHistoryItem"},"type":"array","title":"Messages","description":"Message history"},"total_messages":{"type":"integer","title":"Total Messages","description":"Total messages in session"},"returned_messages":{"type":"integer","title":"Returned Messages","description":"Messages returned"},"has_more":{"type":"boolean","title":"Has More","description":"Whether more messages available"}},"type":"object","required":["session_id","messages","total_messages","returned_messages","has_more"],"title":"GetHistoryResponse","description":"Response for retrieving conversation history.\n\nAttributes:\n session_id: Session identifier\n messages: List of messages in chronological order\n total_messages: Total number of messages in session\n returned_messages: Number of messages returned (may be limited)\n has_more: Whether there are more messages available\n\nExample:\n ```python\n response = GetHistoryResponse(\n session_id=\"ses_abc123\",\n messages=[...],\n total_messages=50,\n returned_messages=20,\n has_more=True\n )\n ```"},"GetMigrationResponse":{"properties":{"migration_id":{"type":"string","title":"Migration Id","description":"Migration ID"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal ID"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Source namespace ID"},"config":{"$ref":"#/components/schemas/MigrationConfig","description":"Migration configuration"},"status":{"$ref":"#/components/schemas/MigrationStatus","description":"Current status"},"progress":{"$ref":"#/components/schemas/MigrationProgress","description":"Progress tracking"},"validation_result":{"anyOf":[{"$ref":"#/components/schemas/ValidationResult"},{"type":"null"}],"description":"Validation result"},"dependency_graph":{"anyOf":[{"$ref":"#/components/schemas/DependencyGraph"},{"type":"null"}],"description":"Dependency graph"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Celery task ID"},"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":"Start timestamp"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Completion timestamp"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error if failed"},"additional_data":{"additionalProperties":true,"type":"object","title":"Additional Data","description":"Additional metadata"}},"type":"object","required":["migration_id","internal_id","namespace_id","config","status","progress","created_at"],"title":"GetMigrationResponse","description":"Response for getting migration details."},"GetPaymentMethodResponse":{"properties":{"has_payment_method":{"type":"boolean","title":"Has Payment Method","description":"Whether organization has a payment method saved"},"payment_method":{"anyOf":[{"$ref":"#/components/schemas/PaymentMethodInfo"},{"type":"null"}],"description":"Payment method details (null if none saved)"},"auto_billing_enabled":{"type":"boolean","title":"Auto Billing Enabled","description":"Whether automatic billing is enabled"}},"type":"object","required":["has_payment_method","auto_billing_enabled"],"title":"GetPaymentMethodResponse","description":"Response with current payment method."},"GetSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace identifier"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User identifier"},"session_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Name","description":"Auto-generated session name based on first conversation"},"agent_config":{"$ref":"#/components/schemas/AgentConfig","description":"Agent configuration"},"user_memory":{"additionalProperties":true,"type":"object","title":"User Memory","description":"User memory/preferences"},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Session status"},"message_count":{"type":"integer","title":"Message Count","description":"Total messages in session"},"stats":{"$ref":"#/components/schemas/SessionStats","description":"Session statistics"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"last_activity_at":{"type":"string","format":"date-time","title":"Last Activity At","description":"Last activity timestamp"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Expiration timestamp"}},"type":"object","required":["session_id","namespace_id","internal_id","agent_config","status","message_count","stats","created_at","updated_at","last_activity_at","expires_at"],"title":"GetSessionResponse","description":"Response for retrieving session metadata.\n\nAttributes:\n session_id: Session identifier\n namespace_id: Namespace identifier\n internal_id: Organization internal ID\n user_id: Optional user identifier\n session_name: Auto-generated session name (null until first message)\n agent_config: Agent configuration\n user_memory: User memory/preferences\n status: Session status\n message_count: Total messages in session\n stats: Session statistics\n created_at: Creation timestamp\n updated_at: Last update timestamp\n last_activity_at: Last activity timestamp\n expires_at: Expiration timestamp\n\nExample:\n ```python\n response = GetSessionResponse(\n session_id=\"ses_abc123\",\n namespace_id=\"ns_xyz789\",\n internal_id=\"int_abc123\",\n session_name=\"Video search for ML tutorials\",\n agent_config=AgentConfig(...),\n status=\"active\",\n message_count=10,\n stats=SessionStats(...)\n )\n ```"},"GoogleDriveConfig":{"properties":{"provider_type":{"type":"string","const":"google_drive","title":"Provider Type","default":"google_drive"},"credentials":{"oneOf":[{"$ref":"#/components/schemas/GoogleDriveServiceAccountCredentials"},{"$ref":"#/components/schemas/GoogleDriveOAuthCredentials"}],"title":"Credentials","description":"REQUIRED. Authentication credentials for Google Drive API access. Choose service_account for production (recommended) or oauth for personal access. The 'type' field determines which credential type is used.","discriminator":{"propertyName":"type","mapping":{"oauth":"#/components/schemas/GoogleDriveOAuthCredentials","service_account":"#/components/schemas/GoogleDriveServiceAccountCredentials"}}},"shared_drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shared Drive Id","description":"NOT REQUIRED. Google Workspace shared drive (Team Drive) identifier. When provided, sync operations are scoped to this shared drive only. When omitted, syncs from 'My Drive' of the authenticated account. Find ID: Open shared drive in browser, copy ID from URL. Format: 0A{alphanumeric-string}","examples":["0AH-Xabc123def456","0ABcDeFgHiJkLmNoPqR"]},"impersonate_user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impersonate User","description":"NOT REQUIRED. Email address to impersonate when using service account credentials. Requires domain-wide delegation to be enabled for the service account. Used in G Suite environments to access files as a specific user. When omitted, uses the service account's own access. Format: Valid email address in the G Suite domain.","examples":["user@example.com","admin@company.com"]}},"type":"object","required":["credentials"],"title":"GoogleDriveConfig","description":"Google Drive and Google Workspace shared drive configuration.\n\nThis configuration enables Mixpeek to connect to Google Drive for automated\nfile ingestion and synchronization. Supports both personal Drive and Google\nWorkspace shared drives (formerly Team Drives).\n\nAuthentication Options:\n - Service Account: Recommended for production. No user interaction required.\n - OAuth2: Suitable for personal Drive access or development.\n\nRequirements:\n - Google Drive API enabled in Google Cloud Console\n - Appropriate authentication credentials configured\n - Files/folders shared with the service account or OAuth user\n - Network connectivity to drive.googleapis.com\n\nUse Cases:\n - Sync marketing materials from shared drives\n - Ingest documents from team collaboration folders\n - Monitor and process uploaded media files\n - Archive and search historical documents","examples":[{"credentials":{"client_email":"sync@mixpeek-prod-456.iam.gserviceaccount.com","client_id":"123456789012345678901","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","private_key_id":"a1b2c3d4e5f6...","project_id":"mixpeek-prod-456","type":"service_account"},"description":"Service account accessing shared drive","provider_type":"google_drive","shared_drive_id":"0AH-Xabc123def456"},{"credentials":{"client_id":"123456789012-abc.apps.googleusercontent.com","client_secret":"GOCSPX-abc123def456","refresh_token":"1//0abc123def456...","type":"oauth"},"description":"OAuth accessing personal Drive","provider_type":"google_drive"},{"credentials":{"client_email":"sync@enterprise-sync.iam.gserviceaccount.com","client_id":"987654321098765432109","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","private_key_id":"xyz789...","project_id":"enterprise-sync","type":"service_account"},"description":"Service account with domain-wide delegation","impersonate_user":"admin@company.com","provider_type":"google_drive"}]},"GoogleDriveOAuthCredentials":{"properties":{"type":{"type":"string","const":"oauth","title":"Type","default":"oauth"},"client_id":{"type":"string","title":"Client Id","description":"REQUIRED. OAuth 2.0 client ID from Google Cloud Console. Found in the API credentials section. Format: {id}.apps.googleusercontent.com","examples":["123456789012-abcdefghijklmnop.apps.googleusercontent.com"]},"client_secret":{"type":"string","title":"Client Secret","description":"REQUIRED. OAuth 2.0 client secret from Google Cloud Console. SECURITY: This field is encrypted at rest. Never log or expose this value. Format: Alphanumeric string from Google Cloud Console.","examples":["GOCSPX-abc123def456ghi789jkl012"]},"refresh_token":{"type":"string","title":"Refresh Token","description":"REQUIRED. Long-lived refresh token obtained during OAuth consent flow. Used to automatically obtain new access tokens without user interaction. SECURITY: Encrypted at rest. Can be revoked by user at any time. Obtain via: Complete OAuth flow with drive.readonly or drive scope."}},"type":"object","required":["client_id","client_secret","refresh_token"],"title":"GoogleDriveOAuthCredentials","description":"Credentials for Google Drive OAuth2 user authentication.\n\nOAuth2 credentials provide access to Google Drive on behalf of a specific user.\nThis authentication method is suitable when accessing personal Drive files or\nwhen service account delegation is not available.\n\nPrerequisites:\n - Create OAuth 2.0 credentials in Google Cloud Console\n - Configure authorized redirect URIs\n - Complete OAuth consent flow to obtain refresh token\n - Ensure appropriate OAuth scopes are granted (drive.readonly or drive)\n\nSecurity:\n - client_secret and refresh_token are encrypted at rest\n - Access tokens are automatically refreshed and cached temporarily\n - Credentials are scoped to the user who granted consent\n\nUse Cases:\n - Personal Drive file access for individual users\n - Prototyping and development without service account setup\n - Environments where service account delegation is not feasible\n\nLimitations:\n - Requires user interaction during initial setup\n - Access is limited to files the consenting user can access\n - Refresh tokens can be revoked by the user"},"GoogleDriveServiceAccountCredentials":{"properties":{"type":{"type":"string","const":"service_account","title":"Type","default":"service_account"},"project_id":{"type":"string","title":"Project Id","description":"REQUIRED. Google Cloud project ID where the service account was created. Found in the JSON key file as 'project_id'. Format: lowercase alphanumeric with hyphens (e.g., 'my-project-123').","examples":["mixpeek-prod-456","customer-ingestion"]},"private_key_id":{"type":"string","title":"Private Key Id","description":"REQUIRED. Unique identifier for the private key. Found in the JSON key file as 'private_key_id'. Format: 40-character hexadecimal string.","examples":["a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"]},"private_key":{"type":"string","title":"Private Key","description":"REQUIRED. PEM-encoded RSA private key for authentication. Found in the JSON key file as 'private_key'. SECURITY: This field is encrypted at rest. Never log or expose this value. Format: Must include BEGIN/END PRIVATE KEY markers."},"client_email":{"type":"string","title":"Client Email","description":"REQUIRED. Service account email address. Found in the JSON key file as 'client_email'. Share Drive files/folders with this email to grant access. Format: {account-name}@{project-id}.iam.gserviceaccount.com","examples":["mixpeek-sync@my-project-123.iam.gserviceaccount.com","ingestion@customer-project.iam.gserviceaccount.com"]},"client_id":{"type":"string","title":"Client Id","description":"REQUIRED. Numeric service account identifier. Found in the JSON key file as 'client_id'. Format: 21-digit numeric string.","examples":["123456789012345678901"]}},"type":"object","required":["project_id","private_key_id","private_key","client_email","client_id"],"title":"GoogleDriveServiceAccountCredentials","description":"Credentials for Google Drive service account authentication.\n\nService accounts provide server-to-server authentication for Google Drive\nwithout requiring user interaction. They are ideal for automated sync operations.\n\nPrerequisites:\n - Create a service account in Google Cloud Console\n - Enable Google Drive API for the project\n - Download the JSON key file\n - Share target Drive files/folders with the service account email\n\nSecurity:\n - private_key field is encrypted at rest using MongoDB client-side field level encryption\n - Credentials never appear in logs or API responses\n - Use domain-wide delegation for G Suite environments\n\nUse Cases:\n - Automated ingestion pipelines from shared drives\n - Scheduled sync operations without user interaction\n - Service-to-service integration for enterprise deployments"},"GoogleModel":{"type":"string","enum":["gemini-2.5-flash","gemini-2.5-pro"],"title":"GoogleModel","description":"Google Gemini model identifiers for LLM generation.\n\nGemini models excel at multimodal understanding with best-in-class video support.\nAll models support text, images, video, audio, and PDFs.\n\nValues:\n GEMINI_2_5_FLASH: Gemini 2.5 Flash model (recommended)\n - Use for: Fastest generation, highest quality multimodal\n - Context: 1M tokens\n - Multimodal: Text, images, video (up to 2hr), audio, PDFs\n - Cost: $0.15/1M input, $0.60/1M output\n - When to use: Default choice for all Gemini use cases\n\n GEMINI_2_5_PRO: Gemini 2.5 Pro model\n - Use for: Higher quality reasoning, complex tasks\n - Context: 1M tokens\n - Cost: $1.25/1M input, $10.00/1M output\n\nNote: Gemini 2.0 and 1.5 models are deprecated.\nUse GEMINI_2_5_FLASH instead."},"GroundTruthQuery":{"properties":{"query_id":{"type":"string","title":"Query Id","description":"Unique identifier for this query within the dataset"},"query_input":{"additionalProperties":true,"type":"object","title":"Query Input","description":"Query input in the same format as retriever execution (e.g., {'text': '...'})"},"relevant_documents":{"items":{"type":"string"},"type":"array","title":"Relevant Documents","description":"List of feature_ids that are relevant for this query"},"relevance_scores":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Relevance Scores","description":"Optional graded relevance scores (doc_id -> score, 0-5 where 5 is most relevant). Used for NDCG calculation."}},"type":"object","required":["query_id","query_input","relevant_documents"],"title":"GroundTruthQuery","description":"Single query with ground truth relevance labels.\n\nThis represents one query in an evaluation dataset, along with the list\nof documents that are considered relevant for that query."},"GroupByField":{"properties":{"field":{"type":"string","title":"Field","description":"The field path to group by. Supports dot notation for nested fields (e.g., 'metadata.category'). For date fields, can be combined with date_trunc or date_part.","examples":["metadata.category","status","created_at","metadata.user_id"]},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Optional alias for the grouped field in results. If not provided, uses the field name. Useful for nested fields to create simpler result names.","examples":["category","upload_date","user"]},"date_trunc":{"anyOf":[{"$ref":"#/components/schemas/DateTruncUnit"},{"type":"null"}],"description":"Truncate date field to specified unit. REQUIRED when grouping by date/time periods. Only valid for date/datetime fields. Cannot be used with date_part.","examples":["day","month","hour"]},"date_part":{"anyOf":[{"$ref":"#/components/schemas/DatePartUnit"},{"type":"null"}],"description":"Extract specific part from date field. OPTIONAL for analyzing date patterns. Only valid for date/datetime fields. Cannot be used with date_trunc.","examples":["hour","dayOfWeek","month"]}},"type":"object","required":["field"],"title":"GroupByField","description":"Configuration for grouping by a field.\n\nDefines how to group data by a specific field, with optional transformations.\n\nRequirements:\n - field: REQUIRED, the field to group by\n - alias: OPTIONAL, name for the grouped field in results\n - date_trunc: OPTIONAL, truncate date fields to time periods\n - date_part: OPTIONAL, extract part of date field\n\nExamples:\n - Simple grouping: GroupByField(field=\"metadata.category\")\n - Daily grouping: GroupByField(field=\"created_at\", date_trunc=DateTruncUnit.DAY)\n - Hour of day: GroupByField(field=\"created_at\", date_part=DatePartUnit.HOUR)","examples":[{"alias":"category","description":"Group by category","field":"metadata.category"},{"alias":"date","date_trunc":"day","description":"Group by day","field":"created_at"},{"alias":"hour","date_part":"hour","description":"Group by hour of day","field":"created_at"}]},"GrowthMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket"},"documents_added":{"type":"integer","title":"Documents Added"},"success_rate":{"type":"number","title":"Success Rate"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms"}},"type":"object","required":["time_bucket","documents_added","success_rate","avg_latency_ms"],"title":"GrowthMetric","description":"Document growth metric."},"GrowthMetricsResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__collections__models__TimeRange"},"metrics":{"items":{"$ref":"#/components/schemas/GrowthMetric"},"type":"array","title":"Metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary"}},"type":"object","required":["collection_id","time_range","metrics"],"title":"GrowthMetricsResponse","description":"Document growth trends."},"HDBSCANParams":{"properties":{"min_cluster_size":{"type":"integer","minimum":2.0,"title":"Min Cluster Size","description":"Minimum number of samples in a cluster","default":5},"min_samples":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Min Samples","description":"Number of samples in a neighborhood for a point to be considered a core point. Defaults to min_cluster_size if None"},"cluster_selection_epsilon":{"type":"number","minimum":0.0,"title":"Cluster Selection Epsilon","description":"A distance threshold for cluster selection. Clusters below this value will be merged","default":0.0},"max_cluster_size":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Cluster Size","description":"Maximum number of samples in a cluster. Clusters above this size will be split"},"metric":{"type":"string","title":"Metric","description":"Metric to use for distance computation","default":"euclidean"},"alpha":{"type":"number","exclusiveMinimum":0.0,"title":"Alpha","description":"A distance scaling parameter","default":1.0},"cluster_selection_method":{"type":"string","title":"Cluster Selection Method","description":"Method to select clusters from the condensed tree ('eom' or 'leaf')","default":"eom"},"allow_single_cluster":{"type":"boolean","title":"Allow Single Cluster","description":"Allow HDBSCAN to find only a single cluster","default":false},"prediction_data":{"type":"boolean","title":"Prediction Data","description":"Whether to generate extra data for predicting cluster membership","default":false},"match_reference_implementation":{"type":"boolean","title":"Match Reference Implementation","description":"Whether to match the reference implementation exactly","default":false}},"type":"object","title":"HDBSCANParams","description":"Parameters for HDBSCAN clustering algorithm."},"HTTPAPIConfig":{"properties":{"provider_type":{"type":"string","const":"http_api","title":"Provider Type","default":"http_api"},"credentials":{"anyOf":[{"$ref":"#/components/schemas/HTTPAPIHeaderCredentials"},{"type":"null"}],"description":"Optional HTTP headers for authenticated API endpoints."},"http_method":{"type":"string","enum":["GET","POST"],"title":"Http Method","description":"HTTP method to use when calling the API.","default":"GET"},"request_body":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Request Body","description":"Optional JSON body for POST requests."},"items_path":{"type":"string","title":"Items Path","description":"Dot-notation path to the array of items in the JSON response. Examples: 'hits' for {hits: [...]}, 'data.items' for {data: {items: [...]}}. Leave empty if the response is a top-level array.","default":""},"item_id_field":{"type":"string","title":"Item Id Field","description":"REQUIRED. Field name in each item used as a unique ID for deduplication. Examples: 'id', 'objectID', 'uuid'."},"item_modified_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Modified Field","description":"Optional field name for a timestamp used for incremental sync. Supports ISO 8601 strings and Unix timestamps. Examples: 'updated_at', 'created_at', 'modified'."},"response_content_type":{"type":"string","enum":["json","jsonl"],"title":"Response Content Type","description":"Response format: 'json' (default) or 'jsonl' (newline-delimited JSON).","default":"json"},"user_agent":{"type":"string","title":"User Agent","description":"User-Agent header for API requests.","default":"Mixpeek HTTP API Sync/1.0"},"request_timeout":{"type":"integer","maximum":120.0,"minimum":5.0,"title":"Request Timeout","description":"HTTP request timeout in seconds.","default":30}},"type":"object","required":["item_id_field"],"title":"HTTPAPIConfig","description":"REST/HTTP JSON API configuration. source_path = API URL.\n\nEnables Mixpeek to sync items from any JSON REST API endpoint.\nEach item in the API response becomes a bucket object with its\nJSON body stored as the blob.\n\nAuthentication:\n - Optional HTTP headers (API keys, Bearer tokens, etc.)\n\nRequirements:\n - API must return JSON (or JSONL) response\n - Response must contain an array of items (at root or nested path)\n - Each item must have a unique ID field for deduplication\n\nUse Cases:\n - Sync data from public APIs (Hacker News, GitHub, etc.)\n - Ingest records from internal REST services\n - Poll third-party APIs (Stripe, Shopify, etc.)\n - Monitor any JSON endpoint for new items","examples":[{"description":"Public API (Hacker News Algolia)","item_id_field":"objectID","item_modified_field":"created_at_i","items_path":"hits","provider_type":"http_api","request_timeout":30},{"credentials":{"headers":{"Authorization":"Bearer your-api-key"},"type":"http_headers"},"description":"Authenticated API with Bearer token","item_id_field":"id","item_modified_field":"updated_at","items_path":"data","provider_type":"http_api"},{"description":"POST API with request body","http_method":"POST","item_id_field":"id","items_path":"results","provider_type":"http_api","request_body":{"limit":10,"query":"mixpeek"}},{"description":"JSONL endpoint","item_id_field":"id","items_path":"","provider_type":"http_api","response_content_type":"jsonl"}]},"HTTPAPIHeaderCredentials":{"properties":{"type":{"type":"string","const":"http_headers","title":"Type","default":"http_headers"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"HTTP headers for API requests (e.g., Authorization, X-API-Key)."}},"type":"object","title":"HTTPAPIHeaderCredentials","description":"Optional HTTP credentials for HTTP API endpoints.\n\nSupports arbitrary headers for authentication (API keys, Bearer tokens, etc.).\nSame pattern as RSS credentials but for REST API endpoints.\n\nSecurity:\n - Header values containing secrets are encrypted at rest via CSFLE\n - Common patterns: Authorization: Bearer , X-API-Key: "},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HavingCondition":{"properties":{"field":{"type":"string","title":"Field","description":"The aggregated field to filter on. REQUIRED, must match an aggregation operation alias. Used after aggregation to filter groups. Not a source field, but a computed field.","examples":["total_count","avg_duration","total_views"]},"operator":{"type":"string","title":"Operator","description":"Comparison operator. REQUIRED, valid operators: gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal), eq (equal), ne (not equal).","examples":["gt","gte","lt","lte","eq","ne"]},"value":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"}],"title":"Value","description":"Value to compare against. REQUIRED, type should match aggregation result type. Numeric for COUNT/SUM/AVG, string for grouped values.","examples":[100,60.0,"active"]}},"type":"object","required":["field","operator","value"],"title":"HavingCondition","description":"Filtering condition for aggregated results.\n\nFilters groups after aggregation (like SQL HAVING clause).\n\nRequirements:\n - field: REQUIRED, the aggregation alias to filter on\n - operator: REQUIRED, comparison operator\n - value: REQUIRED, value to compare against\n\nExamples:\n - Keep high-count groups: HavingCondition(field=\"total_count\", operator=\"gt\", value=100)\n - Filter by average: HavingCondition(field=\"avg_duration\", operator=\"gte\", value=60)","examples":[{"description":"Groups with more than 100 items","field":"total_count","operator":"gt","value":100},{"description":"Average duration at least 60 seconds","field":"avg_duration","operator":"gte","value":60}]},"HealthCheck":{"properties":{"status":{"$ref":"#/components/schemas/HealthStatus-Input","description":"Current health status","default":"healthy"},"last_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Check","description":"When the health was last checked"},"issues":{"items":{"type":"string"},"type":"array","title":"Issues","description":"List of current issues if any"}},"type":"object","title":"HealthCheck","description":"Health check information for a retriever."},"HealthCheckResponse":{"properties":{"status":{"$ref":"#/components/schemas/HealthStatus-Output","description":"Overall API health status"},"data":{"$ref":"#/components/schemas/HealthServiceStatus","description":"Per-service health status flags"},"errors":{"anyOf":[{"$ref":"#/components/schemas/HealthServiceErrors"},{"type":"null"}],"description":"Optional per-service error messages when a service check fails"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta","description":"Optional metadata such as configured object storage bucket/region/endpoint, API URL, and deployment health details (when deep=True)"}},"type":"object","required":["status","data"],"title":"HealthCheckResponse","description":"Health check response model."},"HealthServiceErrors":{"properties":{"cache":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cache","description":"Cache layer error message, if any"},"metadata":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata","description":"Metadata store error message, if any"},"vector_store":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vector Store","description":"Vector database error message, if any"},"object_storage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Object Storage","description":"Object storage error message, if any"},"task_queue":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Queue","description":"Task queue error message, if any"},"inference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference","description":"Inference engine error message, if any"},"analytics":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Analytics","description":"Analytics backend error message, if any"}},"type":"object","title":"HealthServiceErrors","description":"Optional error messages for dependent services (present when a check fails)."},"HealthServiceStatus":{"properties":{"cache":{"type":"boolean","title":"Cache","description":"Cache layer connectivity successful","examples":[true]},"metadata":{"type":"boolean","title":"Metadata","description":"Metadata store connectivity successful","examples":[true]},"vector_store":{"type":"boolean","title":"Vector Store","description":"Vector database connectivity successful","examples":[true]},"object_storage":{"type":"boolean","title":"Object Storage","description":"Object storage connectivity successful","examples":[true]},"task_queue":{"type":"boolean","title":"Task Queue","description":"Task queue execution successful","examples":[true]},"inference":{"type":"boolean","title":"Inference","description":"Inference engine health check successful","examples":[true]},"analytics":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Analytics","description":"Analytics backend healthy (optional, None if disabled)","examples":[true,null]}},"type":"object","required":["cache","metadata","vector_store","object_storage","task_queue","inference"],"title":"HealthServiceStatus","description":"Status flags for dependent services."},"HealthStatus-Input":{"type":"string","enum":["healthy","degraded","unhealthy"],"title":"HealthStatus","description":"Health status of a retriever."},"HealthStatus-Output":{"type":"string","enum":["OK","DEGRADED"],"title":"HealthStatus","description":"Overall health status."},"HeroConfig":{"properties":{"headline":{"type":"string","title":"Headline","description":"Main headline text"},"subheadline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subheadline","description":"Optional subheadline text"},"background_type":{"type":"string","enum":["image","video","gradient","solid"],"title":"Background Type","description":"Background type","default":"solid"},"background_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background Url","description":"URL for image or video background"},"background_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Background Color","description":"Background color for solid/gradient"},"text_color":{"type":"string","title":"Text Color","description":"Hero text color","default":"#FFFFFF"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Logo URL displayed in hero"},"height":{"type":"string","title":"Height","description":"Hero section height","default":"420px"},"cta_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta Label","description":"Call-to-action button label"},"cta_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta Url","description":"Call-to-action button URL"}},"type":"object","required":["headline"],"title":"HeroConfig","description":"Hero section configuration for a page."},"HierarchicalEnrichmentStyle":{"type":"string","enum":["full_chain","best_match","combined"],"title":"HierarchicalEnrichmentStyle","description":"How hierarchical taxonomy results should be structured in enriched documents.\n\nControls the field naming pattern for multi-tier taxonomy enrichment."},"HierarchicalNode-Input":{"properties":{"collection_id":{"type":"string","pattern":"^col_[a-zA-Z0-9_]+$","title":"Collection Id","description":"REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category.","examples":["col_executives","col_managers","col_employees","col_products_phones","col_electronics"]},"parent_collection_id":{"anyOf":[{"type":"string","pattern":"^col_[a-zA-Z0-9_]+$"},{"type":"null"}],"title":"Parent Collection Id","description":"OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy.","examples":["col_employees","col_managers","col_products",null]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation.","examples":["Executive Leadership","Management Team","All Employees","Mobile Phones","Electronics",null]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided.","examples":["Top-level executives with strategic decision-making authority","Mid-level managers overseeing teams and projects","High-end smartphones with premium features",null]},"keywords":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Keywords","description":"OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified.","examples":[["executive","leadership","C-suite","strategic"],["manager","supervisor","team-lead"],["smartphone","mobile","premium","flagship"],null]},"retriever_id":{"anyOf":[{"type":"string","pattern":"^ret_[a-zA-Z0-9_]+$"},{"type":"null"}],"title":"Retriever Id","description":"OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel.","examples":["ret_face_recognition","ret_clip_products","ret_text_semantic",null]},"enrichment_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/EnrichmentField"},"type":"array"},{"type":"null"}],"title":"Enrichment Fields","description":"OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'.","examples":[[{"field_path":"executive_level","merge_mode":"replace"},{"field_path":"budget_authority","merge_mode":"replace"}],[{"field_path":"product_category","merge_mode":"replace"},{"field_path":"tags","merge_mode":"append"}],null]},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level).","examples":[[{"input_key":"face_embedding","path":"features.face","source_type":"vector"}],[{"input_key":"text","path":"description","source_type":"text"}],null]}},"type":"object","required":["collection_id"],"title":"HierarchicalNode","description":"A node in a hierarchical taxonomy representing one level in the tree structure.\n\nEach node represents a collection containing documents at a specific hierarchy level.\nNodes form parent-child relationships to create multi-level taxonomies with\nproperty inheritance. When a document matches a child node, it inherits all\nproperties from parent nodes up to the root.\n\nUse Cases:\n - Define organizational hierarchies: employees ā†’ managers ā†’ executives\n - Create product categorizations: products ā†’ electronics ā†’ phones ā†’ smartphones\n - Build classification trees: industries ā†’ technology ā†’ software\n - Implement face recognition hierarchies: people ā†’ employees ā†’ team members\n - Enable property inheritance: child nodes get all parent properties\n\nHierarchy Behavior:\n - Root nodes: parent_collection_id = None (top of hierarchy)\n - Child nodes: parent_collection_id references parent node's collection_id\n - Property inheritance: Children inherit all parent enrichment_fields\n - Path construction: Creates path array from root to leaf\n - Multi-level matching: Documents matched at deepest applicable level\n\nConfiguration:\n - Per-node retrievers: Override taxonomy-level retriever for specific nodes\n - Per-node enrichment: Override which fields to enrich at each level\n - Per-node input mappings: Customize retriever inputs per hierarchy level\n - Labels/summaries: Human-readable metadata for UI display\n\nRelated Models:\n - HierarchicalTaxonomyConfig: Contains list of hierarchical nodes\n - TaxonomyAssignment: Result of matching documents to nodes\n - EnrichmentField: Specifies which fields to enrich from node\n\nRequirements:\n - collection_id: REQUIRED - must reference an existing collection\n - parent_collection_id: REQUIRED for non-root nodes (None for root)\n - All other fields: OPTIONAL with inheritance from taxonomy-level config","examples":[{"collection_id":"col_employees","description":"Root node - All employees (no parent)","enrichment_fields":[{"field_path":"employee_id","merge_mode":"replace"},{"field_path":"department","merge_mode":"replace"}],"input_mappings":[{"input_key":"face_embedding","path":"features.face","source_type":"vector"}],"keywords":["employee","staff","personnel"],"label":"All Employees","retriever_id":"ret_face_recognition","summary":"Complete employee directory with basic information"},{"collection_id":"col_managers","description":"Mid-level node - Managers (child of employees)","enrichment_fields":[{"field_path":"team_size","merge_mode":"replace"},{"field_path":"reports_to","merge_mode":"replace"}],"keywords":["manager","supervisor","team-lead"],"label":"Management Team","parent_collection_id":"col_employees","summary":"Managers overseeing teams and projects"},{"collection_id":"col_executives","description":"Leaf node - Executives (child of managers)","enrichment_fields":[{"field_path":"executive_level","merge_mode":"replace"},{"field_path":"budget_authority","merge_mode":"replace"}],"keywords":["executive","leadership","C-suite"],"label":"Executive Leadership","parent_collection_id":"col_managers","summary":"C-suite and VP-level executives with strategic authority"},{"collection_id":"col_products","description":"Product hierarchy - Root category","enrichment_fields":[{"field_path":"product_id","merge_mode":"replace"},{"field_path":"tags","merge_mode":"append"}],"keywords":["product","catalog","inventory"],"label":"All Products","retriever_id":"ret_clip_products","summary":"Complete product catalog"},{"collection_id":"col_electronics","description":"Product hierarchy - Electronics category","enrichment_fields":[{"field_path":"warranty_years","merge_mode":"replace"}],"keywords":["electronics","devices","tech"],"label":"Electronics","parent_collection_id":"col_products","summary":"Electronic devices and accessories"},{"collection_id":"col_test_category","description":"Minimal node - Only required fields","parent_collection_id":"col_test_root"}]},"HierarchicalNode-Output":{"properties":{"collection_id":{"type":"string","pattern":"^col_[a-zA-Z0-9_]+$","title":"Collection Id","description":"REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category.","examples":["col_executives","col_managers","col_employees","col_products_phones","col_electronics"]},"parent_collection_id":{"anyOf":[{"type":"string","pattern":"^col_[a-zA-Z0-9_]+$"},{"type":"null"}],"title":"Parent Collection Id","description":"OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy.","examples":["col_employees","col_managers","col_products",null]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation.","examples":["Executive Leadership","Management Team","All Employees","Mobile Phones","Electronics",null]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided.","examples":["Top-level executives with strategic decision-making authority","Mid-level managers overseeing teams and projects","High-end smartphones with premium features",null]},"keywords":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Keywords","description":"OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified.","examples":[["executive","leadership","C-suite","strategic"],["manager","supervisor","team-lead"],["smartphone","mobile","premium","flagship"],null]},"retriever_id":{"anyOf":[{"type":"string","pattern":"^ret_[a-zA-Z0-9_]+$"},{"type":"null"}],"title":"Retriever Id","description":"OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel.","examples":["ret_face_recognition","ret_clip_products","ret_text_semantic",null]},"enrichment_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/EnrichmentField"},"type":"array"},{"type":"null"}],"title":"Enrichment Fields","description":"OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'.","examples":[[{"field_path":"executive_level","merge_mode":"replace"},{"field_path":"budget_authority","merge_mode":"replace"}],[{"field_path":"product_category","merge_mode":"replace"},{"field_path":"tags","merge_mode":"append"}],null]},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level).","examples":[[{"input_key":"face_embedding","path":"features.face","source_type":"vector"}],[{"input_key":"text","path":"description","source_type":"text"}],null]}},"type":"object","required":["collection_id"],"title":"HierarchicalNode","description":"A node in a hierarchical taxonomy representing one level in the tree structure.\n\nEach node represents a collection containing documents at a specific hierarchy level.\nNodes form parent-child relationships to create multi-level taxonomies with\nproperty inheritance. When a document matches a child node, it inherits all\nproperties from parent nodes up to the root.\n\nUse Cases:\n - Define organizational hierarchies: employees ā†’ managers ā†’ executives\n - Create product categorizations: products ā†’ electronics ā†’ phones ā†’ smartphones\n - Build classification trees: industries ā†’ technology ā†’ software\n - Implement face recognition hierarchies: people ā†’ employees ā†’ team members\n - Enable property inheritance: child nodes get all parent properties\n\nHierarchy Behavior:\n - Root nodes: parent_collection_id = None (top of hierarchy)\n - Child nodes: parent_collection_id references parent node's collection_id\n - Property inheritance: Children inherit all parent enrichment_fields\n - Path construction: Creates path array from root to leaf\n - Multi-level matching: Documents matched at deepest applicable level\n\nConfiguration:\n - Per-node retrievers: Override taxonomy-level retriever for specific nodes\n - Per-node enrichment: Override which fields to enrich at each level\n - Per-node input mappings: Customize retriever inputs per hierarchy level\n - Labels/summaries: Human-readable metadata for UI display\n\nRelated Models:\n - HierarchicalTaxonomyConfig: Contains list of hierarchical nodes\n - TaxonomyAssignment: Result of matching documents to nodes\n - EnrichmentField: Specifies which fields to enrich from node\n\nRequirements:\n - collection_id: REQUIRED - must reference an existing collection\n - parent_collection_id: REQUIRED for non-root nodes (None for root)\n - All other fields: OPTIONAL with inheritance from taxonomy-level config","examples":[{"collection_id":"col_employees","description":"Root node - All employees (no parent)","enrichment_fields":[{"field_path":"employee_id","merge_mode":"replace"},{"field_path":"department","merge_mode":"replace"}],"input_mappings":[{"input_key":"face_embedding","path":"features.face","source_type":"vector"}],"keywords":["employee","staff","personnel"],"label":"All Employees","retriever_id":"ret_face_recognition","summary":"Complete employee directory with basic information"},{"collection_id":"col_managers","description":"Mid-level node - Managers (child of employees)","enrichment_fields":[{"field_path":"team_size","merge_mode":"replace"},{"field_path":"reports_to","merge_mode":"replace"}],"keywords":["manager","supervisor","team-lead"],"label":"Management Team","parent_collection_id":"col_employees","summary":"Managers overseeing teams and projects"},{"collection_id":"col_executives","description":"Leaf node - Executives (child of managers)","enrichment_fields":[{"field_path":"executive_level","merge_mode":"replace"},{"field_path":"budget_authority","merge_mode":"replace"}],"keywords":["executive","leadership","C-suite"],"label":"Executive Leadership","parent_collection_id":"col_managers","summary":"C-suite and VP-level executives with strategic authority"},{"collection_id":"col_products","description":"Product hierarchy - Root category","enrichment_fields":[{"field_path":"product_id","merge_mode":"replace"},{"field_path":"tags","merge_mode":"append"}],"keywords":["product","catalog","inventory"],"label":"All Products","retriever_id":"ret_clip_products","summary":"Complete product catalog"},{"collection_id":"col_electronics","description":"Product hierarchy - Electronics category","enrichment_fields":[{"field_path":"warranty_years","merge_mode":"replace"}],"keywords":["electronics","devices","tech"],"label":"Electronics","parent_collection_id":"col_products","summary":"Electronic devices and accessories"},{"collection_id":"col_test_category","description":"Minimal node - Only required fields","parent_collection_id":"col_test_root"}]},"HierarchicalTaxonomyConfig-Input":{"properties":{"taxonomy_type":{"type":"string","const":"hierarchical","title":"Taxonomy Type","description":"Discriminator identifying this as a hierarchical taxonomy.","default":"hierarchical"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Default retriever to use for all nodes unless overridden per-node."},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"Default input mappings for all nodes unless overridden per-node."},"inference_strategy":{"anyOf":[{"$ref":"#/components/schemas/HierarchyInferenceStrategy"},{"type":"null"}],"description":"Strategy for inferring hierarchy structure from collections. Can be 'schema' (overlap-based), 'cluster' (clustering-based), or 'llm' (AI-based). When set, will infer relationships from inference_collections."},"inference_collections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inference Collections","description":"Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration."},"llm_provider":{"anyOf":[{"type":"string","const":"openai_chat_v1"},{"type":"null"}],"title":"Llm Provider","description":"LLM provider to use for hierarchy inference (default openai_chat_v1)"},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model","description":"LLM model name (e.g., gpt-4o-mini)"},"llm_prompt_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Prompt Template","description":"Optional prompt template. Variables available: {collection_id}, {collection_name}."},"llm_sample_size":{"type":"integer","title":"Llm Sample Size","description":"Optional number of sample docs to include in prompts (0 = disabled).","default":0},"cluster_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Cluster Ids","description":"Cluster IDs to use for CLUSTER inference strategy"},"cluster_overlap_threshold":{"type":"number","title":"Cluster Overlap Threshold","description":"Minimum overlap ratio to establish parent-child relationship between clusters","default":0.7},"hierarchical_nodes":{"anyOf":[{"items":{"$ref":"#/components/schemas/HierarchicalNode-Input"},"type":"array"},{"type":"null"}],"title":"Hierarchical Nodes","description":"Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others."},"step_analytics":{"anyOf":[{"$ref":"#/components/schemas/StepAnalyticsConfig-Input"},{"type":"null"}],"description":"Optional configuration for step transition analytics. Enables tracking how documents progress through hierarchical taxonomy nodes over time (e.g., content workflow tracking from 'draft' to 'published'). If not provided, only basic assignment events are logged."}},"type":"object","title":"HierarchicalTaxonomyConfig","description":"Hybrid hierarchical taxonomy configuration supporting inference with manual additions.\n\nAll hierarchical taxonomies are hybrid:\n- Base hierarchy can be inferred via schema, clustering, or LLM\n- Additional collections can be explicitly added with specific retrievers\n- Supports mixing inference strategies with manual additions/overrides\n\nExamples:\n1. Pure inference: Set inference_strategy + inference_collections\n2. Pure manual: Set hierarchical_nodes only\n3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes\n (infers base from collections, adds/overrides with explicit nodes)","examples":[{"hierarchical_nodes":[{"collection_id":"col_employees_v1"},{"collection_id":"col_executives_v1","parent_collection_id":"col_employees_v1"}],"input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"retriever_id":"ret_face_v1","taxonomy_type":"hierarchical"},{"inference_collections":["col_people_v1","col_employees_v1","col_managers_v1"],"inference_strategy":"schema","input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"retriever_id":"ret_face_v1","taxonomy_type":"hierarchical"},{"hierarchical_nodes":[{"collection_id":"col_special_products","enrichment_fields":[{"field_path":"premium_tags","merge_mode":"append"}],"parent_collection_id":"col_products_v1","retriever_id":"ret_special_v1"}],"inference_collections":["col_products_v1","col_categories_v1"],"inference_strategy":"cluster","retriever_id":"ret_clip_v1","taxonomy_type":"hierarchical"}]},"HierarchicalTaxonomyConfig-Output":{"properties":{"taxonomy_type":{"type":"string","const":"hierarchical","title":"Taxonomy Type","description":"Discriminator identifying this as a hierarchical taxonomy.","default":"hierarchical"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Default retriever to use for all nodes unless overridden per-node."},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"Default input mappings for all nodes unless overridden per-node."},"inference_strategy":{"anyOf":[{"$ref":"#/components/schemas/HierarchyInferenceStrategy"},{"type":"null"}],"description":"Strategy for inferring hierarchy structure from collections. Can be 'schema' (overlap-based), 'cluster' (clustering-based), or 'llm' (AI-based). When set, will infer relationships from inference_collections."},"inference_collections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inference Collections","description":"Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration."},"llm_provider":{"anyOf":[{"type":"string","const":"openai_chat_v1"},{"type":"null"}],"title":"Llm Provider","description":"LLM provider to use for hierarchy inference (default openai_chat_v1)"},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model","description":"LLM model name (e.g., gpt-4o-mini)"},"llm_prompt_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Prompt Template","description":"Optional prompt template. Variables available: {collection_id}, {collection_name}."},"llm_sample_size":{"type":"integer","title":"Llm Sample Size","description":"Optional number of sample docs to include in prompts (0 = disabled).","default":0},"cluster_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Cluster Ids","description":"Cluster IDs to use for CLUSTER inference strategy"},"cluster_overlap_threshold":{"type":"number","title":"Cluster Overlap Threshold","description":"Minimum overlap ratio to establish parent-child relationship between clusters","default":0.7},"hierarchical_nodes":{"anyOf":[{"items":{"$ref":"#/components/schemas/HierarchicalNode-Output"},"type":"array"},{"type":"null"}],"title":"Hierarchical Nodes","description":"Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others."},"step_analytics":{"anyOf":[{"$ref":"#/components/schemas/StepAnalyticsConfig-Output"},{"type":"null"}],"description":"Optional configuration for step transition analytics. Enables tracking how documents progress through hierarchical taxonomy nodes over time (e.g., content workflow tracking from 'draft' to 'published'). If not provided, only basic assignment events are logged."}},"type":"object","title":"HierarchicalTaxonomyConfig","description":"Hybrid hierarchical taxonomy configuration supporting inference with manual additions.\n\nAll hierarchical taxonomies are hybrid:\n- Base hierarchy can be inferred via schema, clustering, or LLM\n- Additional collections can be explicitly added with specific retrievers\n- Supports mixing inference strategies with manual additions/overrides\n\nExamples:\n1. Pure inference: Set inference_strategy + inference_collections\n2. Pure manual: Set hierarchical_nodes only\n3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes\n (infers base from collections, adds/overrides with explicit nodes)","examples":[{"hierarchical_nodes":[{"collection_id":"col_employees_v1"},{"collection_id":"col_executives_v1","parent_collection_id":"col_employees_v1"}],"input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"retriever_id":"ret_face_v1","taxonomy_type":"hierarchical"},{"inference_collections":["col_people_v1","col_employees_v1","col_managers_v1"],"inference_strategy":"schema","input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"retriever_id":"ret_face_v1","taxonomy_type":"hierarchical"},{"hierarchical_nodes":[{"collection_id":"col_special_products","enrichment_fields":[{"field_path":"premium_tags","merge_mode":"append"}],"parent_collection_id":"col_products_v1","retriever_id":"ret_special_v1"}],"inference_collections":["col_products_v1","col_categories_v1"],"inference_strategy":"cluster","retriever_id":"ret_clip_v1","taxonomy_type":"hierarchical"}]},"HierarchyInferenceStrategy":{"type":"string","enum":["schema","cluster","llm"],"title":"HierarchyInferenceStrategy","description":"Strategy for inferring the base hierarchy structure.\n\nCan be combined with manual overrides via hierarchical_nodes for hybrid configuration:\n- SCHEMA: Infer based on overlapping collection schemas\n- CLUSTER: Infer based on clustering algorithms and overlap detection\n- LLM: Infer using AI/language models"},"ImageExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"image_extractor","title":"Extractor Type","description":"Discriminator field for parameter type identification.","default":"image_extractor"},"enable_thumbnails":{"type":"boolean","title":"Enable Thumbnails","description":"Whether to generate thumbnail images.","default":true},"use_cdn":{"type":"boolean","title":"Use Cdn","description":"Whether to use CloudFront CDN for thumbnail delivery.","default":false}},"type":"object","title":"ImageExtractorParams","description":"Parameters for the Image Extractor.","examples":[{"enable_thumbnails":true,"extractor_type":"image_extractor","use_cdn":false}]},"IndexRecommendation":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Field to index"},"query_count":{"type":"integer","title":"Query Count","description":"Number of queries using this field"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"slow_query_count":{"type":"integer","title":"Slow Query Count","description":"Queries slower than 500ms"},"very_slow_query_count":{"type":"integer","title":"Very Slow Query Count","description":"Queries slower than 1000ms"},"priority_score":{"type":"number","title":"Priority Score","description":"Priority score for indexing"},"recommendation":{"type":"string","title":"Recommendation","description":"Human-readable recommendation level"},"mongodb_index_command":{"type":"string","title":"Mongodb Index Command","description":"Ready-to-use MongoDB index command"}},"type":"object","required":["field_name","query_count","avg_latency_ms","p95_latency_ms","slow_query_count","very_slow_query_count","priority_score","recommendation","mongodb_index_command"],"title":"IndexRecommendation","description":"MongoDB index recommendation."},"IndexRecommendationsResponse":{"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"},"recommendations":{"items":{"$ref":"#/components/schemas/IndexRecommendation"},"type":"array","title":"Recommendations","description":"Index recommendations"},"summary":{"additionalProperties":{"type":"integer"},"type":"object","title":"Summary","description":"Summary statistics (high_priority, medium_priority, low_priority counts)"}},"type":"object","required":["namespace_id","time_range_days","recommendations","summary"],"title":"IndexRecommendationsResponse","description":"Response for index recommendations endpoint."},"IndexSuggestion":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Field name to index"},"query_count_24h":{"type":"integer","title":"Query Count 24H","description":"Number of queries using this field in last 24 hours"},"query_count_7d":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Query Count 7D","description":"Number of queries in last 7 days"},"suggested_type":{"type":"string","title":"Suggested Type","description":"Suggested index type (keyword, integer, float, etc.)"},"is_indexed":{"type":"boolean","title":"Is Indexed","description":"Whether field is already indexed"},"first_seen":{"type":"string","format":"date-time","title":"First Seen","description":"First time field was seen in filters"},"last_seen":{"type":"string","format":"date-time","title":"Last Seen","description":"Most recent usage"},"estimated_performance_gain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Performance Gain","description":"Estimated query performance improvement (e.g., '60-80%')"}},"type":"object","required":["field_name","query_count_24h","suggested_type","is_indexed","first_seen","last_seen"],"title":"IndexSuggestion","description":"Suggestion for creating a payload index."},"IndexSuggestionsResponse":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace being analyzed"},"analysis_period":{"type":"string","title":"Analysis Period","description":"Time period analyzed (e.g., '24h', '7d')"},"suggestions":{"items":{"$ref":"#/components/schemas/IndexSuggestion"},"type":"array","title":"Suggestions","description":"List of index suggestions"},"auto_create_enabled":{"type":"boolean","title":"Auto Create Enabled","description":"Whether auto-indexing is enabled for this namespace"},"next_auto_create_run":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Auto Create Run","description":"Next scheduled auto-creation run (if enabled)"}},"type":"object","required":["namespace_id","analysis_period","suggestions","auto_create_enabled"],"title":"IndexSuggestionsResponse","description":"Response containing index suggestions for a namespace."},"InputMapping":{"properties":{"input_key":{"type":"string","title":"Input Key","description":"Key used in the constructed inputs payload."},"source_type":{"anyOf":[{"$ref":"#/components/schemas/InputSourceType"},{"type":"null"}],"description":"Source of the value (payload, literal, vector)."},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Dot-notation path inside payload/vector when source_type is PAYLOAD or VECTOR."},"override":{"anyOf":[{},{"type":"null"}],"title":"Override","description":"Static value used when source_type is LITERAL. Overrides any path."}},"type":"object","required":["input_key"],"title":"InputMapping","description":"Declarative mapping for building inputs from various sources.\n\n- input_key: The key used in the constructed inputs payload\n- source_type: Where to fetch the value (payload, literal, vector)\n- path: Dot-notation path when source_type is PAYLOAD or VECTOR\n- override: Static value when source_type is LITERAL","examples":[{"input_key":"query_text","path":"content.title","source_type":"payload"},{"input_key":"lang","override":"en","source_type":"literal"},{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}]},"InputMappingSource":{"properties":{"source_type":{"type":"string","enum":["document_field","constant"],"title":"Source Type","description":"Where the value comes from"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"JSONPath to document field (when source_type='document_field')","examples":["features.video_embedding","metadata.category","_taxonomy_product_label"]},"value":{"anyOf":[{},{"type":"null"}],"title":"Value","description":"Constant value to use (when source_type='constant')","examples":["col_known_incidents",0.85,true]}},"type":"object","required":["source_type"],"title":"InputMappingSource","description":"Defines how to get a value for a retriever input.\n\nCan be a document field reference or a constant value.\n\nAttributes:\n source_type: Where the value comes from ('document_field' or 'constant')\n path: JSONPath to document field (when source_type='document_field')\n value: Constant value to use (when source_type='constant')"},"InputRenderingConfig-Input":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Name of the input field (matches retriever input_schema key)","examples":["query","image_url","video_url","category"]},"field_schema":{"$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.)"},"input_type":{"type":"string","title":"Input Type","description":"UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)","default":"text","examples":["text","select","file","multiselect"]},"label":{"type":"string","title":"Label","description":"Human-readable label for the input","examples":["Search Query","Upload Image","Select Category"]},"placeholder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Placeholder","description":"Placeholder text for the input","examples":["Enter search terms...","Drag and drop or click to upload"]},"helper_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Helper Text","description":"Helper text displayed below the input to guide users","examples":["Describe the aesthetic, outfit, or vibe you're looking for","Enter keywords separated by commas","Use natural language to describe what you're searching for"]},"suggestions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suggestions","description":"Pre-filled suggestion chips that users can click to populate the input","examples":[["streetwear urban","clean girl minimal","summer haul bright"],["wireless headphones","laptop under $1000","gaming mouse"],["minimalist","oversized hoodie","aesthetic vibe"]]},"required":{"type":"boolean","title":"Required","description":"Whether this input is required","default":true},"order":{"type":"integer","minimum":0.0,"title":"Order","description":"Display order (lower numbers appear first)","default":0}},"type":"object","required":["field_name","field_schema","label"],"title":"InputRenderingConfig","description":"Configuration for how to render an input field in the public UI.\n\nMaps to BucketSchemaField structure for consistency with how we define\ninput types across the system.","examples":[{"field_name":"query","field_schema":{"description":"Text search query","examples":["red sports car","sunset over ocean"],"type":"string"},"helper_text":"Describe the aesthetic, outfit, or vibe you're looking for","label":"Search by style","order":0,"placeholder":"Try: oversized hoodie streetwear urban","required":true,"suggestions":["streetwear urban","clean girl minimal","summer haul bright","minimalist aesthetic"]},{"field_name":"image_url","field_schema":{"description":"Image for visual search","examples":["https://example.com/image.jpg"],"type":"image"},"helper_text":"Upload an image to find visually similar items","label":"Upload Image","order":1,"placeholder":"Drop image or paste URL","required":false}]},"InputRenderingConfig-Output":{"properties":{"field_name":{"type":"string","title":"Field Name","description":"Name of the input field (matches retriever input_schema key)","examples":["query","image_url","video_url","category"]},"field_schema":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Output","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.)"},"input_type":{"type":"string","title":"Input Type","description":"UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)","default":"text","examples":["text","select","file","multiselect"]},"label":{"type":"string","title":"Label","description":"Human-readable label for the input","examples":["Search Query","Upload Image","Select Category"]},"placeholder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Placeholder","description":"Placeholder text for the input","examples":["Enter search terms...","Drag and drop or click to upload"]},"helper_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Helper Text","description":"Helper text displayed below the input to guide users","examples":["Describe the aesthetic, outfit, or vibe you're looking for","Enter keywords separated by commas","Use natural language to describe what you're searching for"]},"suggestions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suggestions","description":"Pre-filled suggestion chips that users can click to populate the input","examples":[["streetwear urban","clean girl minimal","summer haul bright"],["wireless headphones","laptop under $1000","gaming mouse"],["minimalist","oversized hoodie","aesthetic vibe"]]},"required":{"type":"boolean","title":"Required","description":"Whether this input is required","default":true},"order":{"type":"integer","minimum":0.0,"title":"Order","description":"Display order (lower numbers appear first)","default":0}},"type":"object","required":["field_name","field_schema","label"],"title":"InputRenderingConfig","description":"Configuration for how to render an input field in the public UI.\n\nMaps to BucketSchemaField structure for consistency with how we define\ninput types across the system.","examples":[{"field_name":"query","field_schema":{"description":"Text search query","examples":["red sports car","sunset over ocean"],"type":"string"},"helper_text":"Describe the aesthetic, outfit, or vibe you're looking for","label":"Search by style","order":0,"placeholder":"Try: oversized hoodie streetwear urban","required":true,"suggestions":["streetwear urban","clean girl minimal","summer haul bright","minimalist aesthetic"]},{"field_name":"image_url","field_schema":{"description":"Image for visual search","examples":["https://example.com/image.jpg"],"type":"image"},"helper_text":"Upload an image to find visually similar items","label":"Upload Image","order":1,"placeholder":"Drop image or paste URL","required":false}]},"InputSourceType":{"type":"string","enum":["payload","literal","vector"],"title":"InputSourceType","description":"Where the value for an input should be retrieved from."},"InstagramConfig":{"properties":{"provider_type":{"type":"string","const":"instagram","title":"Provider Type","default":"instagram"},"credentials":{"$ref":"#/components/schemas/InstagramOAuthCredentials","description":"OAuth credentials for Instagram Graph API access."},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"OAuth scopes granted during authorization.","default":["instagram_basic","instagram_manage_insights","pages_show_list"]},"business_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Account Id","description":"Instagram Business Account ID if different from the user ID. Auto-populated from OAuth flow."}},"type":"object","required":["credentials"],"title":"InstagramConfig","description":"Instagram Business/Creator account configuration via Meta Graph API.\n\nEnables Mixpeek to sync media (posts, reels, carousels) from Instagram\naccounts using the official Instagram Graph API. Each media item becomes\na bucket object with metadata (caption, likes, comments, permalink).\n\nAuthentication:\n - OAuth 2.0 via Meta Developer Console\n - Long-lived tokens (60 days) with automatic refresh\n\nRequirements:\n - Instagram Business or Creator account\n - Facebook Page linked to the Instagram account\n - Meta app with instagram_basic permission\n\nUse Cases:\n - Sync creator content for talent analysis\n - Monitor competitor ad creatives\n - Build social media content libraries for multimodal search","examples":[{"credentials":{"access_token":"IGQ...","client_id":"123456789","client_secret":"app_secret_here","instagram_user_id":"17841400000000000","instagram_username":"mybrand","token_expires_at":"2025-04-01T00:00:00Z","type":"oauth"},"description":"Instagram Business account via OAuth","provider_type":"instagram","scopes":["instagram_basic","instagram_manage_insights"]}]},"InstagramOAuthCredentials":{"properties":{"type":{"type":"string","const":"oauth","title":"Type","default":"oauth"},"client_id":{"type":"string","title":"Client Id","description":"Instagram App ID from Meta Developer Console."},"client_secret":{"type":"string","title":"Client Secret","description":"SECURITY: Encrypted at rest via CSFLE. Instagram App Secret from Meta Developer Console."},"access_token":{"type":"string","title":"Access Token","description":"SECURITY: Encrypted at rest. Long-lived Instagram access token (60-day validity)."},"token_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Token Expires At","description":"Token expiration timestamp. Used to trigger proactive refresh."},"instagram_user_id":{"type":"string","title":"Instagram User Id","description":"Instagram User ID of the account that authorized access."},"instagram_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instagram Username","description":"Instagram username for display purposes."}},"type":"object","required":["client_id","client_secret","access_token","instagram_user_id"],"title":"InstagramOAuthCredentials","description":"Credentials for Instagram Graph API OAuth2 authentication.\n\nInstagram uses Meta's OAuth2 flow to obtain access tokens. The flow\nproduces a short-lived token which is exchanged for a long-lived token\n(valid for 60 days). Long-lived tokens can be refreshed before expiry.\n\nPrerequisites:\n - Meta Developer account with an Instagram app\n - Instagram Business or Creator account linked to a Facebook Page\n - App must have instagram_basic permission approved\n\nSecurity:\n - client_secret and access_token encrypted at rest via CSFLE\n - Long-lived tokens must be refreshed before 60-day expiry\n - Token refresh happens automatically during sync execution"},"InstantiateBucketTemplateRequest":{"properties":{"bucket_name":{"type":"string","maxLength":100,"minLength":1,"title":"Bucket Name","description":"Name for the new bucket"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description override for the bucket"}},"type":"object","required":["bucket_name"],"title":"InstantiateBucketTemplateRequest","description":"Request to instantiate a bucket from a template.","examples":[{"bucket_name":"my_product_images","description":"Product images for e-commerce store"}]},"InstantiateClusterTemplateRequest":{"properties":{"cluster_name":{"type":"string","maxLength":100,"minLength":1,"title":"Cluster Name","description":"Name for the new cluster"},"collection_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Collection Ids","description":"Collection IDs to use for the cluster"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description override for the cluster"}},"type":"object","required":["cluster_name","collection_ids"],"title":"InstantiateClusterTemplateRequest","description":"Request to instantiate a cluster from a template.","examples":[{"cluster_name":"my_product_clusters","collection_ids":["col_products"],"description":"Cluster products by visual similarity"}]},"InstantiateCollectionTemplateRequest":{"properties":{"collection_name":{"type":"string","maxLength":100,"minLength":1,"title":"Collection Name","description":"Name for the new collection"},"bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bucket Ids","description":"Bucket IDs to use for the collection (for bucket sources)"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID to use for the collection (for collection sources)"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description override for the collection"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Optional tags for the collection"}},"type":"object","required":["collection_name"],"title":"InstantiateCollectionTemplateRequest","description":"Request to instantiate a collection from a template.","examples":[{"bucket_ids":["bkt_products"],"collection_name":"my_product_embeddings","description":"Image embeddings for product catalog","tags":["production","products"]}]},"InstantiateRetrieverTemplateRequest":{"properties":{"retriever_name":{"type":"string","maxLength":100,"minLength":1,"title":"Retriever Name","description":"Name for the new retriever"},"collection_identifiers":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Collection Identifiers","description":"Collection identifiers to use for the retriever"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description override for the retriever"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Optional tags for the retriever"}},"type":"object","required":["retriever_name","collection_identifiers"],"title":"InstantiateRetrieverTemplateRequest","description":"Request to instantiate a retriever from a template.","examples":[{"collection_identifiers":["products"],"description":"Semantic search for products","retriever_name":"my_product_search","tags":["production","products"]}]},"InstantiateScaffoldRequest":{"properties":{"namespace_name":{"type":"string","maxLength":100,"minLength":1,"title":"Namespace Name","description":"Name for the new namespace (required, must be unique)"},"namespace_description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Namespace Description","description":"Optional description for the namespace"},"bucket_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Bucket Name","description":"Override default bucket name from scaffold"},"collection_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Collection Name","description":"Override default collection name from scaffold"},"retriever_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Retriever Name","description":"Override default retriever name from scaffold"},"include_sample_data":{"type":"boolean","title":"Include Sample Data","description":"If true, include sample data from demo namespace. If false, create empty resources.","default":false}},"type":"object","required":["namespace_name"],"title":"InstantiateScaffoldRequest","description":"Request to instantiate a scaffold template.\n\nOnly namespace_name is required. Other names use scaffold defaults.\n\nOptions:\n include_sample_data: If true, clone from demo namespace with sample data.\n If false (default), create empty resources.\n\nExample:\n # Empty scaffold\n {\"namespace_name\": \"my_app\"}\n\n # With sample data\n {\"namespace_name\": \"my_app\", \"include_sample_data\": true}","examples":[{"namespace_name":"my_video_app"},{"include_sample_data":true,"namespace_name":"my_video_app"},{"bucket_name":"my_videos","collection_name":"video_embeddings","namespace_description":"Video search application","namespace_name":"my_video_app","retriever_name":"video_search"}]},"InstantiateTaxonomyTemplateRequest":{"properties":{"taxonomy_name":{"type":"string","maxLength":100,"minLength":1,"title":"Taxonomy Name","description":"Name for the new taxonomy"},"collection_config":{"additionalProperties":{"type":"string"},"type":"object","title":"Collection Config","description":"Collection configuration for the taxonomy. For flat taxonomies: {'collection_id': 'col_xxx'} For hierarchical taxonomies: maps node collection IDs to actual collection IDs, e.g., {'col_template_root': 'col_actual_root', 'col_template_child': 'col_actual_child'}"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description override for the taxonomy"}},"type":"object","required":["taxonomy_name","collection_config"],"title":"InstantiateTaxonomyTemplateRequest","description":"Request to instantiate a taxonomy from a template.","examples":[{"collection_config":{"collection_id":"col_products_v1"},"description":"Product categorization taxonomy","taxonomy_name":"my_product_categories"},{"collection_config":{"col_employees":"col_my_employees","col_executives":"col_my_executives","col_managers":"col_my_managers"},"description":"Organization hierarchy taxonomy","taxonomy_name":"my_org_hierarchy"}]},"InstantiateTemplateRequest":{"properties":{"namespace_name":{"type":"string","maxLength":50,"minLength":3,"title":"Namespace Name","description":"Name for the new namespace. REQUIRED. Must be unique within your organization. Used as identifier and display name. Format: 3-50 characters, alphanumeric with underscores/hyphens, lowercase recommended. Cannot match existing namespace names.","examples":["my_ecommerce_demo","test_media_lib","demo_docs_2024"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description for the namespace. NOT REQUIRED. If not provided, uses the template's description. Useful for adding context about your specific use case. Format: 0-500 characters, plain text.","examples":["Testing e-commerce search features for Q4 launch","Demo environment for customer presentation",null]}},"type":"object","required":["namespace_name"],"title":"InstantiateTemplateRequest","description":"Request to create a new namespace from a template.\n\nInstantiation clones all data from the template's source namespace including:\n- Namespace configuration (feature extractors, indexes)\n- Qdrant vectors and payloads (pre-computed embeddings)\n- MongoDB metadata (collections, documents)\n\nThe process is fast (<5 seconds) because data is cloned, not reprocessed.\n\nUse Cases:\n - First-time user onboarding with working examples\n - Creating demo environments for sales/trials\n - Spinning up test environments with known data\n - Providing industry-specific starting points\n\nRequirements:\n - namespace_name: REQUIRED, must be unique within organization\n - description: OPTIONAL, defaults to template description if not provided\n\nValidation:\n - Checks namespace name uniqueness before creation\n - Validates template exists and is active\n - Ensures source namespace is accessible","examples":[{"namespace_name":"my_demo"},{"description":"Demo environment for ACME Corp presentation","namespace_name":"customer_demo_2024"},{"description":"Testing product similarity search before production","namespace_name":"test_ecommerce_search"}]},"InstantiatedBucketTemplateResponse":{"properties":{"bucket_id":{"type":"string","title":"Bucket Id","description":"ID of the created bucket"},"bucket_name":{"type":"string","title":"Bucket Name","description":"Name of the created bucket"},"template_id":{"type":"string","title":"Template Id","description":"ID of the template used"},"status":{"type":"string","title":"Status","description":"Status of the instantiation","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when bucket was created"}},"type":"object","required":["bucket_id","bucket_name","template_id"],"title":"InstantiatedBucketTemplateResponse","description":"Response after instantiating a bucket template.","examples":[{"bucket_id":"bkt_abc123","bucket_name":"my_product_images","created_at":"2025-01-15T12:00:00Z","status":"created","template_id":"tmpl_image_bucket"}]},"InstantiatedClusterTemplateResponse":{"properties":{"cluster_id":{"type":"string","title":"Cluster Id","description":"ID of the created cluster"},"cluster_name":{"type":"string","title":"Cluster Name","description":"Name of the created cluster"},"template_id":{"type":"string","title":"Template Id","description":"ID of the template used"},"status":{"type":"string","title":"Status","description":"Status of the instantiation","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when cluster was created"}},"type":"object","required":["cluster_id","cluster_name","template_id"],"title":"InstantiatedClusterTemplateResponse","description":"Response after instantiating a cluster template.","examples":[{"cluster_id":"clust_abc123","cluster_name":"my_product_clusters","created_at":"2025-01-15T12:00:00Z","status":"created","template_id":"tmpl_visual_clustering"}]},"InstantiatedCollectionTemplateResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"ID of the created collection"},"collection_name":{"type":"string","title":"Collection Name","description":"Name of the created collection"},"template_id":{"type":"string","title":"Template Id","description":"ID of the template used"},"status":{"type":"string","title":"Status","description":"Status of the instantiation","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when collection was created"}},"type":"object","required":["collection_id","collection_name","template_id"],"title":"InstantiatedCollectionTemplateResponse","description":"Response after instantiating a collection template.","examples":[{"collection_id":"col_abc123","collection_name":"my_product_embeddings","created_at":"2025-01-15T12:00:00Z","status":"created","template_id":"tmpl_image_embeddings"}]},"InstantiatedRetrieverTemplateResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the created retriever"},"retriever_name":{"type":"string","title":"Retriever Name","description":"Name of the created retriever"},"template_id":{"type":"string","title":"Template Id","description":"ID of the template used"},"status":{"type":"string","title":"Status","description":"Status of the instantiation","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when retriever was created"}},"type":"object","required":["retriever_id","retriever_name","template_id"],"title":"InstantiatedRetrieverTemplateResponse","description":"Response after instantiating a retriever template.","examples":[{"created_at":"2025-01-15T12:00:00Z","retriever_id":"ret_abc123","retriever_name":"my_product_search","status":"created","template_id":"tmpl_semantic_search"}]},"InstantiatedScaffoldResponse":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"Created namespace ID (ns_xxx)"},"namespace_name":{"type":"string","title":"Namespace Name","description":"Created namespace name"},"bucket_id":{"type":"string","title":"Bucket Id","description":"Created bucket ID (bkt_xxx)"},"bucket_name":{"type":"string","title":"Bucket Name","description":"Created bucket name"},"collection_id":{"type":"string","title":"Collection Id","description":"Created collection ID (col_xxx)"},"collection_name":{"type":"string","title":"Collection Name","description":"Created collection name"},"retriever_id":{"type":"string","title":"Retriever Id","description":"Created retriever ID (ret_xxx)"},"retriever_name":{"type":"string","title":"Retriever Name","description":"Created retriever name"},"template_id":{"type":"string","title":"Template Id","description":"Scaffold template ID used"},"status":{"type":"string","title":"Status","description":"Status: 'created' on success","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC timestamp of creation"}},"type":"object","required":["namespace_id","namespace_name","bucket_id","bucket_name","collection_id","collection_name","retriever_id","retriever_name","template_id"],"title":"InstantiatedScaffoldResponse","description":"Response after successful scaffold instantiation.\n\nContains IDs and names of all four created resources.\nUse these IDs for subsequent operations:\n- Upload data: POST /v1/buckets/{bucket_id}/objects\n- Process: POST /v1/collections/{collection_id}/batches\n- Search: POST /v1/retrievers/{retriever_id}/retrieve","examples":[{"bucket_id":"bkt_xyz789","bucket_name":"videos","collection_id":"col_def456","collection_name":"video_embeddings","created_at":"2025-01-15T12:00:00Z","namespace_id":"ns_abc123","namespace_name":"my_video_app","retriever_id":"ret_ghi012","retriever_name":"video_search","status":"created","template_id":"tmpl_scaffold_video_search"}]},"InstantiatedTaxonomyTemplateResponse":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"ID of the created taxonomy"},"taxonomy_name":{"type":"string","title":"Taxonomy Name","description":"Name of the created taxonomy"},"template_id":{"type":"string","title":"Template Id","description":"ID of the template used"},"status":{"type":"string","title":"Status","description":"Status of the instantiation","default":"created"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when taxonomy was created"}},"type":"object","required":["taxonomy_id","taxonomy_name","template_id"],"title":"InstantiatedTaxonomyTemplateResponse","description":"Response after instantiating a taxonomy template.","examples":[{"created_at":"2025-01-15T12:00:00Z","status":"created","taxonomy_id":"tax_abc123","taxonomy_name":"my_product_categories","template_id":"tmpl_product_taxonomy"}]},"InstantiatedTemplateResponse":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"ID of the newly created namespace. REQUIRED. Use this ID in the X-Namespace header for all API calls to this namespace. Format: namespace ID starting with 'ns_'. Permanent identifier for the namespace.","examples":["ns_abc123xyz","ns_demo456def","ns_test789ghi"]},"namespace_name":{"type":"string","title":"Namespace Name","description":"Name of the newly created namespace. REQUIRED. Matches the namespace_name from the request. Human-readable identifier shown in UI. Can be used for namespace lookup via GET /namespaces/{name}.","examples":["my_ecommerce_demo","customer_demo_2024","test_media_lib"]},"template_id":{"type":"string","title":"Template Id","description":"ID of the template that was instantiated. REQUIRED. Reference to the source template used for creation. Useful for tracking which template produced this namespace. Format: template ID starting with 'tmpl_'.","examples":["tmpl_ecommerce","tmpl_media_library","tmpl_legal_docs"]},"status":{"type":"string","title":"Status","description":"Instantiation status. REQUIRED. 'cloning' means the namespace is being created and data is being copied. 'ready' means the namespace is fully functional and ready to use. 'failed' means the cloning process encountered an error. Poll GET /namespaces/{namespace_id} to check when status becomes 'ready'. All data is cloned including collections, vectors, retrievers, and taxonomies.","default":"cloning","examples":["cloning","ready","failed"]},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Celery task ID for tracking the clone operation. Can be used to poll task status if needed. Format: UUID string.","examples":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when namespace was created. REQUIRED. Auto-generated by server. Format: ISO 8601 datetime in UTC. Used for auditing and sorting namespaces by creation time."}},"type":"object","required":["namespace_id","namespace_name","template_id"],"title":"InstantiatedTemplateResponse","description":"Response after successful template instantiation.\n\nProvides all information needed to start using the newly created namespace,\nincluding IDs for API calls and status information.\n\nThe namespace is immediately ready for use when status is 'ready'.\nAll collections, documents, and feature stores are fully functional.\n\nUse Cases:\n - Retrieve namespace_id for subsequent API calls\n - Verify instantiation completed successfully\n - Track which template was used for the namespace\n - Record creation timestamp for auditing\n\nFields:\n All fields are REQUIRED and populated by the server.","examples":[{"created_at":"2024-10-31T12:00:00Z","description":"Template instantiation started - cloning in progress","namespace_id":"ns_abc123xyz","namespace_name":"my_ecommerce_demo","status":"cloning","task_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","template_id":"tmpl_ecommerce"},{"created_at":"2024-10-31T14:30:00Z","description":"Customer demo environment ready","namespace_id":"ns_demo456def","namespace_name":"customer_demo_2024","status":"ready","template_id":"tmpl_media_library"},{"created_at":"2024-10-31T16:45:00Z","description":"Test namespace from legal template","namespace_id":"ns_test789ghi","namespace_name":"test_legal_search","status":"cloning","task_id":"b2c3d4e5-f6a7-8901-bcde-f23456789012","template_id":"tmpl_legal_docs"}]},"IntegerIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"integer"},"lookup":{"type":"boolean","title":"Lookup","default":true},"range":{"type":"boolean","title":"Range","default":true}},"type":"object","title":"IntegerIndexParams","description":"Configuration for integer index."},"IntentClassification":{"properties":{"intent":{"type":"string","pattern":"^(execution|setup|ambiguous)$","title":"Intent","description":"Detected intent: 'execution', 'setup', or 'ambiguous'"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Confidence in classification"},"reasoning":{"type":"string","title":"Reasoning","description":"Why this intent was detected"},"suitable_collections":{"items":{"$ref":"#/components/schemas/SuitableCollection"},"type":"array","title":"Suitable Collections","description":"Existing collections that might help"},"recommended_action":{"type":"string","title":"Recommended Action","description":"Next action to take (e.g., 'setup_pipeline', 'execute_retriever')"},"clarification_needed":{"type":"boolean","title":"Clarification Needed","description":"Whether to ask user for clarification"},"clarification_options":{"items":{"$ref":"#/components/schemas/ClarificationOption"},"type":"array","title":"Clarification Options","description":"Options for user if clarification needed"},"keywords_found":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Keywords Found","description":"Keywords found (setup_keywords, execution_keywords, neutral_keywords)"}},"type":"object","required":["intent","confidence","reasoning","recommended_action","clarification_needed"],"title":"IntentClassification","description":"Result of intent detection analysis.\n\nThis model represents the agent's understanding of whether the user wants 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\nAttributes:\n intent: The detected intent (\"execution\", \"setup\", or \"ambiguous\")\n confidence: Confidence score 0.0-1.0\n reasoning: Explanation of why this intent was detected\n suitable_collections: Existing collections that might fulfill the request\n recommended_action: What the agent should do next\n clarification_needed: Whether to ask user for clarification\n clarification_options: Options to present if clarification needed\n keywords_found: Keywords that influenced the classification"},"InteractionResponse":{"properties":{"feature_id":{"type":"string","title":"Feature Id","description":"ID of the document/feature that was interacted with. REQUIRED. This should be the document_id returned in retriever results. Used to track which specific items users engage with.","examples":["doc_abc123","prod_xyz789","feat_12345"]},"interaction_type":{"items":{"$ref":"#/components/schemas/InteractionType"},"type":"array","minItems":1,"title":"Interaction Type","description":"List of interaction types that occurred. REQUIRED. Multiple types can be recorded simultaneously (e.g., VIEW + CLICK + LONG_VIEW for a result the user engaged with). Use the InteractionType enum values.","examples":[["click"],["positive_feedback","click","long_view"],["negative_feedback"],["purchase","click"]]},"position":{"type":"integer","minimum":0.0,"title":"Position","description":"Position in search results where interaction occurred (0-indexed). REQUIRED. Critical for Learning to Rank - helps identify position bias. E.g., position=0 means first result, position=9 means 10th result. Higher engagement at lower positions suggests higher quality.","examples":[0,1,5,15]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.","examples":[{"device":"mobile","duration_ms":5000,"page":"search_results","viewport_position":0.75},{"interaction_reason":"not_relevant","page_number":2,"results_count":50,"search_latency_ms":150}]},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Customer's authenticated user identifier. NOT REQUIRED. Persists across sessions for long-term tracking. Enables personalization and user-specific metrics. Use your application's user ID format.","examples":["user_abc123","customer_456","usr_xyz789"]},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Temporary identifier for a single search session. NOT REQUIRED. Typically 30min-1hr duration. Tracks anonymous and authenticated users within a session. Use to group related queries and understand search journeys.","examples":["sess_abc123","session_xyz789_1234567890"]},"execution_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Id","description":"ID of the retriever execution that generated these results. NOT REQUIRED but HIGHLY RECOMMENDED for training and optimization. Links the interaction back to the exact search query, pipeline configuration, and stage execution that produced the results the user saw. Essential for: fine-tuning embeddings, training rerankers, query understanding, and tracing which pipeline configs produce better user engagement. Retrieve from the retriever execution response and pass to interactions.","examples":["exec_abc123xyz","exec_550e8400e29b41d4"]},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"ID of the retriever that was executed. NOT REQUIRED but RECOMMENDED for multi-retriever analytics. Enables comparing performance across different retriever configurations. If execution_id is provided, retriever_id can be inferred from the execution record.","examples":["ret_abc123","ret_product_search_v2"]},"query_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Query Snapshot","description":"Snapshot of the query input that generated these results. HIGHLY RECOMMENDED for training optimization. Storing the query directly enables 10-100x faster training data extraction by avoiding expensive joins to execution records. Use the same format as retriever query input (e.g., {'text': '...', 'filters': {...}}). Essential for: embedding fine-tuning (query-document pairs), query expansion learning, and analyzing which query patterns lead to better engagement. NOT REQUIRED but strongly recommended for production use cases involving model training.","examples":[{"text":"wireless headphones"},{"filters":{"price":{"lte":1000}},"text":"laptop"},{"context":"summer collection","text":"red shoes"}]},"document_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Document Score","description":"Initial retrieval score of this document when shown to the user. HIGHLY RECOMMENDED for Learning to Rank (LTR). This is a critical feature for reranker training - helps the model learn how to adjust initial scores based on user engagement. Should match the score from the retriever execution results. NOT REQUIRED but strongly recommended for LTR and reranker training.","examples":[0.95,0.87,0.62]},"result_set_size":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Result Set Size","description":"Total number of results shown to the user in this search. NOT REQUIRED but useful for context. Helps understand interaction patterns - clicking position 5 of 10 results is different from position 5 of 100 results. Useful for position bias correction and CTR analysis.","examples":[10,20,50,100]},"interaction_id":{"type":"string","title":"Interaction Id","description":"Unique identifier for this interaction record. System-assigned UUID. Use this to reference the interaction in subsequent requests.","examples":["int_abc123xyz789","550e8400-e29b-41d4-a716-446655440000"]},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp","description":"ISO 8601 timestamp when the interaction was recorded. System-assigned. Used for time-based analysis, training data recency weighting, and temporal trends in user behavior.","examples":["2025-01-15T10:30:00Z","2025-01-15T14:45:30.123Z"]}},"type":"object","required":["feature_id","interaction_type","position","interaction_id"],"title":"InteractionResponse","description":"Response model for a stored interaction.\n\nExtends SearchInteraction with system-assigned fields.","examples":[{"description":"Minimal click interaction (query_snapshot and document_score optional)","execution_id":"exec_minimal_123","feature_id":"doc_abc123","interaction_type":["click"],"position":2,"session_id":"sess_minimal"},{"description":"Simple click interaction with recommended fields for training","document_score":0.85,"feature_id":"doc_abc123","interaction_type":["click"],"position":2,"query_snapshot":{"text":"machine learning tutorials"}},{"description":"Engaged view with metadata and execution tracking","document_score":0.92,"execution_id":"exec_abc123xyz","feature_id":"prod_xyz789","interaction_type":["view","click","long_view"],"metadata":{"device":"mobile","duration_ms":12000,"viewport_position":0.85},"position":0,"query_snapshot":{"filters":{"price":{"lte":100}},"text":"wireless headphones"},"result_set_size":20,"retriever_id":"ret_product_search","session_id":"sess_abc","user_id":"user_123"},{"description":"Negative feedback","document_score":0.78,"feature_id":"doc_bad456","interaction_type":["negative_feedback","return_to_results"],"metadata":{"interaction_reason":"not_relevant"},"position":5,"query_snapshot":{"text":"python tutorial"},"result_set_size":50,"session_id":"sess_xyz"},{"description":"Purchase conversion with full tracking (high-value signal for training)","document_score":0.88,"execution_id":"exec_purchase_789","feature_id":"prod_789","interaction_type":["purchase"],"metadata":{"conversion_time_seconds":120,"purchase_amount":199.99},"position":1,"query_snapshot":{"text":"noise cancelling headphones"},"result_set_size":50,"retriever_id":"ret_product_search","session_id":"sess_purchase_001","user_id":"user_456"}]},"InteractionTuningRecommendation":{"properties":{"recommendation_type":{"type":"string","title":"Recommendation Type","description":"Type of recommendation","examples":["increase_k","adjust_rerank_threshold","enable_cache"]},"current_value":{"anyOf":[{},{"type":"null"}],"title":"Current Value","description":"Current setting value"},"recommended_value":{"title":"Recommended Value","description":"Recommended value"},"expected_impact":{"type":"string","title":"Expected Impact","description":"Expected performance impact"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Confidence score"},"reasoning":{"type":"string","title":"Reasoning","description":"Explanation of recommendation"}},"type":"object","required":["recommendation_type","recommended_value","expected_impact","confidence","reasoning"],"title":"InteractionTuningRecommendation","description":"Recommendation for interaction tuning."},"InteractionTuningResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Retriever identifier"},"analysis_period":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Analysis period"},"recommendations":{"items":{"$ref":"#/components/schemas/InteractionTuningRecommendation"},"type":"array","title":"Recommendations","description":"Tuning recommendations"},"current_performance":{"additionalProperties":true,"type":"object","title":"Current Performance","description":"Current performance baseline"}},"type":"object","required":["retriever_id","analysis_period","recommendations","current_performance"],"title":"InteractionTuningResponse","description":"Response for interaction tuning analysis.","examples":[{"analysis_period":{"end":"2025-10-28T00:00:00Z","start":"2025-10-21T00:00:00Z"},"current_performance":{"avg_latency_ms":145.3,"avg_results":10,"cache_hit_rate":0.72,"p95_latency_ms":287.5},"recommendations":[{"confidence":0.85,"current_value":10,"expected_impact":"Improve recall by ~15%, increase latency by ~8ms","reasoning":"Query patterns show users often click beyond top 10 results","recommendation_type":"increase_k","recommended_value":20}],"retriever_id":"ret_abc123"}]},"InteractionType":{"type":"string","enum":["view","click","positive_feedback","negative_feedback","purchase","add_to_cart","wishlist","long_view","share","bookmark","query_refinement","zero_results","filter_toggle","skip","return_to_results"],"title":"InteractionType","description":"Types of user interactions with search results.\n\nThese interaction types are used to track user behavior and improve retrieval quality\nthrough Learning to Rank (LTR), collaborative filtering, and embedding fine-tuning.\n\nValues:\n VIEW: User viewed a search result\n CLICK: User clicked on a search result\n POSITIVE_FEEDBACK: User explicitly marked result as relevant/helpful\n NEGATIVE_FEEDBACK: User explicitly marked result as not relevant\n PURCHASE: User purchased the item (high-value conversion signal)\n ADD_TO_CART: User added item to cart (mid-funnel signal)\n WISHLIST: User saved item for later (engagement signal)\n LONG_VIEW: User spent significant time viewing (dwell time)\n SHARE: User shared the result (strong engagement signal)\n BOOKMARK: User bookmarked the result\n QUERY_REFINEMENT: User modified their search query\n ZERO_RESULTS: Query yielded no results (helps identify gaps)\n FILTER_TOGGLE: User modified filters (helps understand intent)\n SKIP: User skipped over result to click something lower (negative signal)\n RETURN_TO_RESULTS: User quickly returned to results (negative signal)\n\nUsage in Retrieval Optimization:\n - LTR (Learning to Rank): Train models to predict click-through rates\n - Collaborative Filtering: Find similar users/items based on interactions\n - Embedding Fine-tuning: Adjust embeddings based on what users actually click\n - Query Understanding: Analyze refinements and zero-result queries\n - Result Quality: Identify poorly-performing results via skip/return patterns"},"InteractionWeights":{"properties":{"weights":{"additionalProperties":{"type":"number"},"type":"object","title":"Weights","description":"Mapping of interaction_type -> weight (higher = more important)."}},"type":"object","title":"InteractionWeights","description":"Custom weights for different interaction types when computing metrics.\n\nHigher weights indicate more importance. Purchases typically have higher weight\nthan clicks because they're a stronger signal of user intent.\n\nExample: {\"click\": 1.0, \"purchase\": 5.0, \"add_to_cart\": 2.0, \"bookmark\": 1.5}"},"InternalLineageModel":{"properties":{"root_object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Object Id","description":"Original object ID from bucket (root of decomposition tree). All documents derived from the same object share this ID.","examples":["obj_video123","obj_document456"]},"root_bucket_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Root Bucket Id","description":"Bucket ID containing the root object.","examples":["bkt_marketing","bkt_documents"]},"source_type":{"anyOf":[{"type":"string","enum":["bucket","collection"]},{"type":"null"}],"title":"Source Type","description":"Type of immediate parent source. 'bucket': Document created directly from bucket object (tier 1). 'collection': Document created from another collection (tier 2+).","examples":["bucket","collection"]},"source_object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Object Id","description":"Object ID of immediate parent when source_type='bucket'.","examples":["obj_video123"]},"source_document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Document Id","description":"Document ID of immediate parent when source_type='collection'.","examples":["doc_frame050"]},"source_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Collection Id","description":"Collection ID of immediate parent when source_type='collection'.","examples":["col_video_frames"]},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Materialized lineage path string (e.g., 'bkt_123/col_456/col_789').","examples":["bkt_marketing/col_video_frames","bkt_docs/col_chapters/col_paragraphs"]},"chain":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Chain","description":"Ordered list of processing steps from root object to this document. Each step contains: collection_id, feature_extractor_id, document_id, timestamp.","examples":[[{"collection_id":"col_frames","feature_extractor_id":"multimodal_extractor_v1","timestamp":"2025-10-31T10:00:00Z"}]]}},"additionalProperties":true,"type":"object","title":"InternalLineageModel","description":"Lineage tracking information for document provenance.\n\nTracks the complete processing history from the original bucket object\nthrough all transformation stages in the decomposition tree."},"InternalPayloadModel":{"properties":{"internal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Internal Id","description":"Organization/tenant identifier for multi-tenancy isolation.","examples":["org_abc123"]},"namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Namespace Id","description":"Namespace identifier within the organization.","examples":["ns_xyz789"]},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Document identifier (also at root level for convenience).","examples":["doc_f8966ff29c18e20c6b45e053"]},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection identifier (also at root level for convenience).","examples":["col_articles","col_video_frames"]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"ISO 8601 timestamp when document was created.","examples":["2025-10-31T10:00:00Z"]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"ISO 8601 timestamp when document was last updated.","examples":["2025-10-31T10:05:00Z"]},"lineage":{"anyOf":[{"$ref":"#/components/schemas/InternalLineageModel"},{"type":"null"}],"description":"Document lineage and provenance tracking."},"processing":{"anyOf":[{"$ref":"#/components/schemas/InternalProcessingModel"},{"type":"null"}],"description":"Processing history and provenance metadata."},"source_blobs":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Source Blobs","description":"Blobs that constituted the original source object.","examples":[[{"blob_id":"blob_video_001","blob_property":"video","blob_type":"video"}]]},"document_blobs":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Document Blobs","description":"Blobs generated during document processing (thumbnails, etc.).","examples":[[{"field":"thumbnail","role":"thumbnail","type":"image","url":"s3://..."}]]},"source_details":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Source Details","description":"Enrichment tracking and source detail entries."},"modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality","description":"Content modality (text, image, video, audio, etc.).","examples":["text","image","video","audio"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"System metadata including ingestion_status, feature_extractor_config_hash, and other processing-related information.","examples":[{"feature_extractor_config_hash":"abc123","ingestion_status":"COMPLETED"}]},"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mime Type","description":"MIME type of the source content.","examples":["video/mp4","image/jpeg","text/plain"]},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes","description":"Size of the source content in bytes.","examples":[1024000,5242880]},"content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Hash","description":"SHA256 hash of the source content for deduplication.","examples":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]}},"additionalProperties":true,"type":"object","title":"InternalPayloadModel","description":"Complete _internal field structure for Qdrant document payloads.\n\nAll Mixpeek-managed system fields are namespaced under this structure to:\n- Prevent collision with user-defined fields\n- Provide clear separation of system vs user data\n- Enable filtering on internal fields via _internal.field_name paths\n\nThis structure is stored in Qdrant and returned in API responses.","examples":[{"collection_id":"col_articles","created_at":"2025-10-31T10:00:00Z","document_id":"doc_f8966ff29c","internal_id":"org_abc123","lineage":{"path":"bkt_content/col_articles","root_bucket_id":"bkt_content","root_object_id":"obj_article_001","source_object_id":"obj_article_001","source_type":"bucket"},"metadata":{"ingestion_status":"COMPLETED"},"modality":"text","namespace_id":"ns_xyz789","updated_at":"2025-10-31T10:00:00Z"}]},"InternalProcessingModel":{"properties":{"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"Original URL before S3 mirroring (for URL-based ingestion).","examples":["https://example.com/video.mp4"]},"object_key_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Object Key Source","description":"S3 key source identifier."},"detected_mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detected Mime Type","description":"MIME type detected during canonicalization.","examples":["video/mp4","image/jpeg","application/pdf"]},"history":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"History","description":"Processing steps history with timestamps and operations.","examples":[[{"operation":"taxonomy_join","taxonomy_ids_applied":["tax_industries"],"timestamp":"2025-10-22T11:03:22Z"}]]},"taxonomy_lineage":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Taxonomy Lineage","description":"Taxonomy enrichment entries applied to this document."},"last_health_check":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Last Health Check","description":"Last health check result (for batch processing)."}},"additionalProperties":true,"type":"object","title":"InternalProcessingModel","description":"Processing and provenance tracking information.\n\nConsolidates all processing-related metadata including source URLs,\nprocessing history, and taxonomy enrichment lineage."},"InvoiceInfo":{"properties":{"invoice_id":{"type":"string","title":"Invoice Id","description":"Stripe Invoice ID","examples":["in_1ABC2DEF3GHI"]},"invoice_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Url","description":"Stripe-hosted invoice URL (None if not yet finalized)","examples":["https://invoice.stripe.com/i/inv_1ABC2DEF3GHI"]},"invoice_pdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Pdf","description":"PDF download URL (None if not yet finalized)","examples":["https://invoice.stripe.com/i/inv_1ABC2DEF3GHI/pdf"]},"amount_due":{"type":"integer","title":"Amount Due","description":"Amount due in cents","examples":[2345]},"amount_paid":{"type":"integer","title":"Amount Paid","description":"Amount paid in cents","examples":[2345]},"status":{"type":"string","title":"Status","description":"Invoice status","examples":["paid","open","void","uncollectible"]},"billing_month":{"type":"string","title":"Billing Month","description":"Billing month (YYYY-MM)","examples":["2025-11"]},"total_credits":{"type":"integer","title":"Total Credits","description":"Total credits billed","examples":[23450]},"created":{"type":"string","format":"date-time","title":"Created","description":"When invoice was created"},"paid_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid At","description":"When invoice was paid"}},"type":"object","required":["invoice_id","amount_due","amount_paid","status","billing_month","total_credits","created"],"title":"InvoiceInfo","description":"Information about a monthly invoice."},"InvoiceListResponse":{"properties":{"invoices":{"items":{"$ref":"#/components/schemas/InvoiceInfo"},"type":"array","title":"Invoices","description":"List of invoices"},"total":{"type":"integer","title":"Total","description":"Total number of invoices"},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more invoices"}},"type":"object","required":["total","has_more"],"title":"InvoiceListResponse","description":"Response with list of invoices."},"JoinMode":{"type":"string","enum":["on_demand","batch"],"title":"JoinMode"},"JoinResponse":{"properties":{"stats":{"$ref":"#/components/schemas/JoinStats"},"results":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Results"}},"type":"object","required":["stats"],"title":"JoinResponse"},"JoinStats":{"properties":{"processed_docs":{"type":"integer","title":"Processed Docs","default":0},"batches":{"type":"integer","title":"Batches","default":0},"errors":{"type":"integer","title":"Errors","default":0}},"type":"object","title":"JoinStats"},"KMeansParams":{"properties":{"n_clusters":{"type":"integer","maximum":1000.0,"minimum":2.0,"title":"N Clusters","description":"Number of clusters to form","default":8},"max_iter":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Max Iter","description":"Maximum number of iterations","default":300},"random_state":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Random State","description":"Random seed for reproducibility","default":42},"n_init":{"type":"integer","minimum":1.0,"title":"N Init","description":"Number of times k-means will run with different centroid seeds","default":10},"tol":{"type":"number","exclusiveMinimum":0.0,"title":"Tol","description":"Tolerance for convergence","default":0.0001},"init":{"type":"string","title":"Init","description":"Method for initialization ('k-means++' or 'random')","default":"k-means++"},"verbose":{"type":"integer","minimum":0.0,"title":"Verbose","description":"Verbosity mode","default":0},"copy_x":{"type":"boolean","title":"Copy X","description":"If True, the original data is not modified","default":true},"algorithm":{"type":"string","title":"Algorithm","description":"K-means algorithm to use ('lloyd', 'elkan', or 'auto')","default":"lloyd"}},"type":"object","title":"KMeansParams","description":"Parameters for K-Means clustering algorithm."},"KeyStatus":{"type":"string","enum":["active","revoked","expired"],"title":"KeyStatus","description":"Lifecycle state of an API key.\n\nStatus determines whether an API key can be used for authentication:\n\n- ACTIVE: Key is valid and can be used for API requests. Last_used_at timestamp\n is updated on each successful authentication.\n- REVOKED: Key has been manually revoked by an admin or user. Cannot be\n reactivated. A new key must be created instead.\n- EXPIRED: Key has passed its expires_at timestamp. Automatically set by the\n authentication system. Cannot be reactivated."},"KeysetPaginationParams":{"properties":{"method":{"$ref":"#/components/schemas/PaginationMethod","description":"Constant identifying keyset pagination (REQUIRED).","default":"keyset"},"limit":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","description":"Maximum number of documents to return per page (REQUIRED). Default: 10.","default":10},"after":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"After","description":"Last seen keyset marker from previous response (OPTIONAL). Must include all sort fields. Example: {'score': 0.73, 'id': 'doc_20'}. null for first page, then use next_cursor from response"}},"type":"object","title":"KeysetPaginationParams","description":"Stateless keyset pagination relying on last seen sort key.\n\nBest for: High-performance pagination, large result sets, stable sorting\n\nHow it works:\n- Uses actual field values as pagination markers\n- Database can use indexes efficiently (WHERE score < 0.73)\n- No offset calculation or server state\n- Requires deterministic sort order (e.g., score DESC, id ASC)\n- Most efficient pagination method\n\nRequirements:\n- Results must be sorted consistently\n- Sort fields must be in the \"after\" marker\n- Example: sorted by (score DESC, id ASC) ā†’ after: {score: 0.73, id: \"doc_20\"}\n\nAdvantages:\n- No server-side state (truly stateless)\n- Consistent even with concurrent writes\n- Database can use indexes (fast for large datasets)\n- No offset performance degradation\n\nUse when:\n- You have stable, deterministic sort fields\n- Working with large result sets (10k+ docs)\n- Maximum performance is critical\n- You need infinite scroll with best efficiency\n\nExample flow:\n1. Request: {\"method\": \"keyset\", \"limit\": 20, \"after\": null}\n2. Response: {\"documents\": [...], \"next_cursor\": {\"score\": 0.85, \"id\": \"doc_20\"}}\n3. Request: {\"method\": \"keyset\", \"limit\": 20, \"after\": {\"score\": 0.85, \"id\": \"doc_20\"}}"},"KeywordIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"keyword"},"is_tenant":{"type":"boolean","title":"Is Tenant","default":false}},"type":"object","title":"KeywordIndexParams","description":"Configuration for keyword index."},"LLMLabeling-Input":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Whether to generate labels for clusters using LLM. When enabled, clusters will have semantic labels like 'High-Performance Laptops' instead of generic labels like 'Cluster 0'.","default":false},"labeling_inputs":{"anyOf":[{"$ref":"#/components/schemas/LLMLabelingInput-Input"},{"type":"null"}],"description":"Input configuration for LLM labeling. Supports flexible input mappings for multimodal inputs (text, images, videos, audio). Use input_mappings for advanced multimodal labeling with providers like Gemini. If not provided (null/undefined), the full document payload will be serialized as JSON and sent to the LLM, providing complete context for semantic labeling."},"provider":{"anyOf":[{"$ref":"#/components/schemas/LLMProvider"},{"type":"null"}],"description":"LLM provider to use for labeling. Supported providers:\n- openai: GPT models (GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini)\n- google: Gemini models (Gemini 2.5 Flash, Gemini 1.5 Flash)\n- anthropic: Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku)\n\nIf not specified, automatically inferred from model_name.","examples":["openai","google","anthropic"]},"model_name":{"anyOf":[{"$ref":"#/components/schemas/OpenAIModel"},{"$ref":"#/components/schemas/GoogleModel"},{"$ref":"#/components/schemas/AnthropicModel"},{"type":"null"}],"title":"Model Name","description":"REQUIRED when enabled=True. Specific LLM model to use for cluster labeling. All models are defined as enums for type safety.\n\nOpenAI Models (provider='openai'):\n- gpt-4o-2024-08-06: Highest quality, best for production ($2.50/$10 per 1M tokens)\n- gpt-4o-mini-2024-07-18: Cost-effective, recommended for most use cases ($0.15/$0.60 per 1M tokens)\n- gpt-4.1-2025-04-14: Latest model, future-proofed\n- gpt-4.1-mini-2025-04-14: Latest cost-optimized model\n- o3-mini-2025-01-31: Advanced reasoning, best for complex clustering\n\nGoogle Models (provider='google'):\n- gemini-2.0-flash: Fastest, latest multimodal model, recommended ($0.075/$0.30 per 1M tokens)\n- gemini-2.0-flash-exp: Experimental version with latest features ($0.075/$0.30 per 1M tokens)\n\nAnthropic Models (provider='anthropic'):\n- claude-3-5-sonnet-20241022: Best reasoning, 200K context ($3/$15 per 1M tokens)\n- claude-3-5-haiku-20241022: Fast, cost-effective ($0.25/$1.25 per 1M tokens)\n\nRecommendation:\n- Use gemini-2.5-flash (DEFAULT) - multimodal support\n- Use gpt-4o-mini-2024-07-18 for OpenAI compatibility\n- Use gpt-4o-2024-08-06 for highest quality when cost is not a concern","examples":["gemini-2.5-flash","gemini-2.5-pro","gpt-4o-mini-2024-07-18","gpt-4o-2024-08-06","claude-3-5-sonnet-20241022","claude-3-5-haiku-20241022","gpt-4.1-2025-04-14","gpt-4.1-mini-2025-04-14","o3-mini-2025-01-31"]},"include_summary":{"type":"boolean","title":"Include Summary","description":"Whether to generate cluster summaries","default":true},"include_keywords":{"type":"boolean","title":"Include Keywords","description":"Whether to extract keywords for clusters","default":true},"max_samples_per_cluster":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Samples Per Cluster","description":"Maximum representative documents to send to LLM per cluster for semantic analysis","default":10},"sample_text_max_length":{"type":"integer","maximum":500.0,"minimum":50.0,"title":"Sample Text Max Length","description":"Maximum characters per document sample text","default":200},"use_embedding_dedup":{"type":"boolean","title":"Use Embedding Dedup","description":"Enable embedding-based label deduplication to prevent near-duplicate labels (requires sentence-transformers)","default":false},"embedding_similarity_threshold":{"type":"number","maximum":1.0,"minimum":0.5,"title":"Embedding Similarity Threshold","description":"Cosine similarity threshold for duplicate label detection (labels above this are considered duplicates)","default":0.8},"cache_ttl_seconds":{"type":"integer","maximum":2592000.0,"minimum":0.0,"title":"Cache Ttl Seconds","description":"Time-to-live for cached labels in seconds. Labels for clusters with identical representative documents will be reused within this TTL window, reducing LLM API costs. Default: 604800 (7 days). Set to 0 to disable caching.","default":604800},"custom_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Prompt","description":"OPTIONAL. Custom prompt template for LLM labeling. NOT REQUIRED - uses default discriminative prompt if not provided. When provided, completely replaces the default prompt. Your custom prompt receives cluster information but you must format it yourself. Use when: - Need domain-specific labeling (e.g., medical, legal, technical) - Want different label format (e.g., emoji labels, code names) - Require specific output structure - Have custom business logic for categorization Default prompt includes: cluster document samples, forbidden labels for uniqueness, and JSON response format. See engine/clusters/labeling/prompts.py for reference. Example: 'Analyze these product clusters and generate SHORT category names (2-3 words max) focusing on product type and price range. Return JSON: [{\"cluster_id\": \"cl_0\", \"label\": \"...\"}]'","examples":["Analyze these document clusters and generate technical labels (2-3 words). Focus on programming languages and frameworks mentioned. Return JSON: [{'cluster_id': 'cl_0', 'label': '...', 'keywords': [...]}]","Generate emoji-based labels for these clusters. Use 1-2 emojis that represent the main theme. Return JSON: [{'cluster_id': 'cl_0', 'label': 'šŸš€ Tech Innovation'}]",null]},"response_shape":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Shape","description":"OPTIONAL. Define custom structured output for LLM labeling. NOT REQUIRED - uses default structure (label, summary, keywords) if not provided. When provided, LLM output will match this structure and be stored in cluster documents. \n\nTwo modes supported:\n1. Natural language prompt (string): Describe desired output in plain English\n - Service automatically infers JSON schema from your description\n - Example: 'Extract cluster category, confidence score (0-1), and top 3 representative terms'\n - Auto-generates schema with appropriate types (string, number, array, etc.)\n\n2. Explicit JSON schema (dict): Provide complete JSON schema for output structure\n - Full control over output structure, types, and constraints\n - Example: {'type': 'object', 'properties': {'category': {'type': 'string'}, ...}}\n\n\nUse when:\n - Need custom metadata fields (confidence scores, sentiment, complexity)\n - Want domain-specific structure (taxonomy hierarchies, entity extractions)\n - Require specific data types (arrays, nested objects, enums)\n - Have downstream schema requirements\n\n\nOutput fields are automatically added to cluster collection schema and stored in metadata.\nDefault behavior (if not provided): label (string), summary (string), keywords (array of strings)\n","examples":["Extract cluster category, confidence score between 0 and 1, and top 3 representative keywords","Generate cluster theme, sentiment (positive/negative/neutral), and list of key entities",{"properties":{"category":{"description":"Main category","type":"string"},"subcategory":{"description":"Subcategory if applicable","type":"string"},"confidence":{"maximum":1,"minimum":0,"type":"number"},"keywords":{"items":{"type":"string"},"maxItems":5,"type":"array"}},"required":["category","confidence"],"type":"object"},null]},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Provider-specific parameters forwarded to the LLM service. For OpenAI: temperature, max_tokens, top_p, json_output, etc. For Google: temperature, top_k, max_output_tokens, json_output, etc."}},"type":"object","title":"LLMLabeling","description":"Configuration for LLM-based cluster labeling.\n\nSupports multiple LLM providers with comprehensive model selection:\n- OpenAI: GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini (best for quality)\n- Google: Gemini 2.5 Flash, Gemini 1.5 Flash (best for speed and cost)\n- Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku (best for reasoning)\n\nAll models are defined as enums and validated at API level.","examples":[{"description":"Text-only labeling with multiple fields","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"title","path":"title","source_type":"payload"},{"input_key":"description","path":"description","source_type":"payload"},{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-mini-2024-07-18","provider":"openai"},{"description":"Multimodal labeling with images (Gemini)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"headline","source_type":"payload"},{"input_key":"image_url","path":"thumbnail_url","source_type":"payload"}]},"model_name":"gemini-2.0-flash","provider":"google"},{"description":"Multimodal labeling with video (Gemini)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"description","source_type":"payload"},{"input_key":"video_url","path":"video_url","source_type":"payload"}]},"model_name":"gemini-2.0-flash","provider":"google"},{"description":"OpenAI GPT-4o (highest quality, text-only)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-2024-08-06","provider":"openai"},{"description":"Anthropic Claude 3.5 Sonnet (best reasoning)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"claude-3-5-sonnet-20241022","provider":"anthropic"},{"description":"Minimal configuration (uses defaults: text field from payload)","enabled":true},{"custom_prompt":"You are a medical document classifier. Analyze the following patient record clusters and generate HIPAA-compliant category labels (2-3 words) that describe the medical condition or treatment type. DO NOT include patient names or identifiers. Return JSON array: [{\"cluster_id\": \"cl_0\", \"label\": \"...\", \"keywords\": [...]}]","description":"Custom prompt for domain-specific labeling","enabled":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-mini-2024-07-18","provider":"openai"}]},"LLMLabeling-Output":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Whether to generate labels for clusters using LLM. When enabled, clusters will have semantic labels like 'High-Performance Laptops' instead of generic labels like 'Cluster 0'.","default":false},"labeling_inputs":{"anyOf":[{"$ref":"#/components/schemas/LLMLabelingInput-Output"},{"type":"null"}],"description":"Input configuration for LLM labeling. Supports flexible input mappings for multimodal inputs (text, images, videos, audio). Use input_mappings for advanced multimodal labeling with providers like Gemini. If not provided (null/undefined), the full document payload will be serialized as JSON and sent to the LLM, providing complete context for semantic labeling."},"provider":{"anyOf":[{"$ref":"#/components/schemas/LLMProvider"},{"type":"null"}],"description":"LLM provider to use for labeling. Supported providers:\n- openai: GPT models (GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini)\n- google: Gemini models (Gemini 2.5 Flash, Gemini 1.5 Flash)\n- anthropic: Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku)\n\nIf not specified, automatically inferred from model_name.","examples":["openai","google","anthropic"]},"model_name":{"anyOf":[{"$ref":"#/components/schemas/OpenAIModel"},{"$ref":"#/components/schemas/GoogleModel"},{"$ref":"#/components/schemas/AnthropicModel"},{"type":"null"}],"title":"Model Name","description":"REQUIRED when enabled=True. Specific LLM model to use for cluster labeling. All models are defined as enums for type safety.\n\nOpenAI Models (provider='openai'):\n- gpt-4o-2024-08-06: Highest quality, best for production ($2.50/$10 per 1M tokens)\n- gpt-4o-mini-2024-07-18: Cost-effective, recommended for most use cases ($0.15/$0.60 per 1M tokens)\n- gpt-4.1-2025-04-14: Latest model, future-proofed\n- gpt-4.1-mini-2025-04-14: Latest cost-optimized model\n- o3-mini-2025-01-31: Advanced reasoning, best for complex clustering\n\nGoogle Models (provider='google'):\n- gemini-2.0-flash: Fastest, latest multimodal model, recommended ($0.075/$0.30 per 1M tokens)\n- gemini-2.0-flash-exp: Experimental version with latest features ($0.075/$0.30 per 1M tokens)\n\nAnthropic Models (provider='anthropic'):\n- claude-3-5-sonnet-20241022: Best reasoning, 200K context ($3/$15 per 1M tokens)\n- claude-3-5-haiku-20241022: Fast, cost-effective ($0.25/$1.25 per 1M tokens)\n\nRecommendation:\n- Use gemini-2.5-flash (DEFAULT) - multimodal support\n- Use gpt-4o-mini-2024-07-18 for OpenAI compatibility\n- Use gpt-4o-2024-08-06 for highest quality when cost is not a concern","examples":["gemini-2.5-flash","gemini-2.5-pro","gpt-4o-mini-2024-07-18","gpt-4o-2024-08-06","claude-3-5-sonnet-20241022","claude-3-5-haiku-20241022","gpt-4.1-2025-04-14","gpt-4.1-mini-2025-04-14","o3-mini-2025-01-31"]},"include_summary":{"type":"boolean","title":"Include Summary","description":"Whether to generate cluster summaries","default":true},"include_keywords":{"type":"boolean","title":"Include Keywords","description":"Whether to extract keywords for clusters","default":true},"max_samples_per_cluster":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Samples Per Cluster","description":"Maximum representative documents to send to LLM per cluster for semantic analysis","default":10},"sample_text_max_length":{"type":"integer","maximum":500.0,"minimum":50.0,"title":"Sample Text Max Length","description":"Maximum characters per document sample text","default":200},"use_embedding_dedup":{"type":"boolean","title":"Use Embedding Dedup","description":"Enable embedding-based label deduplication to prevent near-duplicate labels (requires sentence-transformers)","default":false},"embedding_similarity_threshold":{"type":"number","maximum":1.0,"minimum":0.5,"title":"Embedding Similarity Threshold","description":"Cosine similarity threshold for duplicate label detection (labels above this are considered duplicates)","default":0.8},"cache_ttl_seconds":{"type":"integer","maximum":2592000.0,"minimum":0.0,"title":"Cache Ttl Seconds","description":"Time-to-live for cached labels in seconds. Labels for clusters with identical representative documents will be reused within this TTL window, reducing LLM API costs. Default: 604800 (7 days). Set to 0 to disable caching.","default":604800},"custom_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Prompt","description":"OPTIONAL. Custom prompt template for LLM labeling. NOT REQUIRED - uses default discriminative prompt if not provided. When provided, completely replaces the default prompt. Your custom prompt receives cluster information but you must format it yourself. Use when: - Need domain-specific labeling (e.g., medical, legal, technical) - Want different label format (e.g., emoji labels, code names) - Require specific output structure - Have custom business logic for categorization Default prompt includes: cluster document samples, forbidden labels for uniqueness, and JSON response format. See engine/clusters/labeling/prompts.py for reference. Example: 'Analyze these product clusters and generate SHORT category names (2-3 words max) focusing on product type and price range. Return JSON: [{\"cluster_id\": \"cl_0\", \"label\": \"...\"}]'","examples":["Analyze these document clusters and generate technical labels (2-3 words). Focus on programming languages and frameworks mentioned. Return JSON: [{'cluster_id': 'cl_0', 'label': '...', 'keywords': [...]}]","Generate emoji-based labels for these clusters. Use 1-2 emojis that represent the main theme. Return JSON: [{'cluster_id': 'cl_0', 'label': 'šŸš€ Tech Innovation'}]",null]},"response_shape":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Shape","description":"OPTIONAL. Define custom structured output for LLM labeling. NOT REQUIRED - uses default structure (label, summary, keywords) if not provided. When provided, LLM output will match this structure and be stored in cluster documents. \n\nTwo modes supported:\n1. Natural language prompt (string): Describe desired output in plain English\n - Service automatically infers JSON schema from your description\n - Example: 'Extract cluster category, confidence score (0-1), and top 3 representative terms'\n - Auto-generates schema with appropriate types (string, number, array, etc.)\n\n2. Explicit JSON schema (dict): Provide complete JSON schema for output structure\n - Full control over output structure, types, and constraints\n - Example: {'type': 'object', 'properties': {'category': {'type': 'string'}, ...}}\n\n\nUse when:\n - Need custom metadata fields (confidence scores, sentiment, complexity)\n - Want domain-specific structure (taxonomy hierarchies, entity extractions)\n - Require specific data types (arrays, nested objects, enums)\n - Have downstream schema requirements\n\n\nOutput fields are automatically added to cluster collection schema and stored in metadata.\nDefault behavior (if not provided): label (string), summary (string), keywords (array of strings)\n","examples":["Extract cluster category, confidence score between 0 and 1, and top 3 representative keywords","Generate cluster theme, sentiment (positive/negative/neutral), and list of key entities",{"properties":{"category":{"description":"Main category","type":"string"},"subcategory":{"description":"Subcategory if applicable","type":"string"},"confidence":{"maximum":1,"minimum":0,"type":"number"},"keywords":{"items":{"type":"string"},"maxItems":5,"type":"array"}},"required":["category","confidence"],"type":"object"},null]},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Provider-specific parameters forwarded to the LLM service. For OpenAI: temperature, max_tokens, top_p, json_output, etc. For Google: temperature, top_k, max_output_tokens, json_output, etc."}},"type":"object","title":"LLMLabeling","description":"Configuration for LLM-based cluster labeling.\n\nSupports multiple LLM providers with comprehensive model selection:\n- OpenAI: GPT-4o, GPT-4o-mini, GPT-4.1, O3-mini (best for quality)\n- Google: Gemini 2.5 Flash, Gemini 1.5 Flash (best for speed and cost)\n- Anthropic: Claude 3.5 Sonnet, Claude 3.5 Haiku (best for reasoning)\n\nAll models are defined as enums and validated at API level.","examples":[{"description":"Text-only labeling with multiple fields","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"title","path":"title","source_type":"payload"},{"input_key":"description","path":"description","source_type":"payload"},{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-mini-2024-07-18","provider":"openai"},{"description":"Multimodal labeling with images (Gemini)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"headline","source_type":"payload"},{"input_key":"image_url","path":"thumbnail_url","source_type":"payload"}]},"model_name":"gemini-2.0-flash","provider":"google"},{"description":"Multimodal labeling with video (Gemini)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"description","source_type":"payload"},{"input_key":"video_url","path":"video_url","source_type":"payload"}]},"model_name":"gemini-2.0-flash","provider":"google"},{"description":"OpenAI GPT-4o (highest quality, text-only)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-2024-08-06","provider":"openai"},{"description":"Anthropic Claude 3.5 Sonnet (best reasoning)","enabled":true,"include_keywords":true,"include_summary":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"claude-3-5-sonnet-20241022","provider":"anthropic"},{"description":"Minimal configuration (uses defaults: text field from payload)","enabled":true},{"custom_prompt":"You are a medical document classifier. Analyze the following patient record clusters and generate HIPAA-compliant category labels (2-3 words) that describe the medical condition or treatment type. DO NOT include patient names or identifiers. Return JSON array: [{\"cluster_id\": \"cl_0\", \"label\": \"...\", \"keywords\": [...]}]","description":"Custom prompt for domain-specific labeling","enabled":true,"labeling_inputs":{"input_mappings":[{"input_key":"text","path":"text","source_type":"payload"}]},"model_name":"gpt-4o-mini-2024-07-18","provider":"openai"}]},"LLMLabelingInput-Input":{"properties":{"input_mappings":{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array","minItems":1,"title":"Input Mappings","description":"Flexible input mappings for constructing LLM context. Supports multimodal inputs (text, image_url, video_url, audio_url). Each mapping specifies how to extract data from document payloads. At least one input mapping is required."}},"type":"object","required":["input_mappings"],"title":"LLMLabelingInput","description":"Input configuration for LLM-based cluster labeling.\n\nSupports flexible input mappings similar to retrievers and buckets,\nallowing multimodal inputs (text, images, videos, audio) for providers\nlike Gemini that support native multimodal understanding.\n\nExamples:\n # Text-only labeling:\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"headline\", source_type=\"payload\", path=\"headline\"),\n InputMapping(input_key=\"description\", source_type=\"payload\", path=\"description\")\n ])\n\n # Multimodal labeling with images:\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"text\", source_type=\"payload\", path=\"headline\"),\n InputMapping(input_key=\"image_url\", source_type=\"payload\", path=\"thumbnail_url\")\n ])\n\n # Multimodal with video (for Gemini):\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"text\", source_type=\"payload\", path=\"description\"),\n InputMapping(input_key=\"video_url\", source_type=\"payload\", path=\"video_url\")\n ])"},"LLMLabelingInput-Output":{"properties":{"input_mappings":{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array","minItems":1,"title":"Input Mappings","description":"Flexible input mappings for constructing LLM context. Supports multimodal inputs (text, image_url, video_url, audio_url). Each mapping specifies how to extract data from document payloads. At least one input mapping is required."}},"type":"object","required":["input_mappings"],"title":"LLMLabelingInput","description":"Input configuration for LLM-based cluster labeling.\n\nSupports flexible input mappings similar to retrievers and buckets,\nallowing multimodal inputs (text, images, videos, audio) for providers\nlike Gemini that support native multimodal understanding.\n\nExamples:\n # Text-only labeling:\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"headline\", source_type=\"payload\", path=\"headline\"),\n InputMapping(input_key=\"description\", source_type=\"payload\", path=\"description\")\n ])\n\n # Multimodal labeling with images:\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"text\", source_type=\"payload\", path=\"headline\"),\n InputMapping(input_key=\"image_url\", source_type=\"payload\", path=\"thumbnail_url\")\n ])\n\n # Multimodal with video (for Gemini):\n LLMLabelingInput(input_mappings=[\n InputMapping(input_key=\"text\", source_type=\"payload\", path=\"description\"),\n InputMapping(input_key=\"video_url\", source_type=\"payload\", path=\"video_url\")\n ])"},"LLMProvider":{"type":"string","enum":["openai","google","anthropic"],"title":"LLMProvider","description":"Supported LLM providers for content generation.\n\nEach provider has different strengths, pricing, and multimodal capabilities.\nChoose based on your use case, performance requirements, and budget.\n\nValues:\n OPENAI: OpenAI GPT models (GPT-4o, GPT-4.1, O3-mini)\n - Best for: General purpose, vision tasks, structured outputs\n - Multimodal: Text, images\n - Performance: Fast (100-500ms), reliable\n - Cost: Moderate to high ($0.15-$10 per 1M tokens)\n - Use when: Need high-quality generation with vision support\n\n GOOGLE: Google Gemini models (Gemini 1.5 Flash, Gemini 2.5 Flash)\n - Best for: Fast generation, video understanding, cost-efficiency\n - Multimodal: Text, images, video, audio, PDFs\n - Performance: Very fast (50-200ms)\n - Cost: Low to moderate ($0.075-$0.40 per 1M tokens)\n - Use when: Need video/audio/PDF support or cost-efficiency\n\n ANTHROPIC: Anthropic Claude models (Claude 3.5 Sonnet, Claude 3.5 Haiku)\n - Best for: Long context, complex reasoning, safety\n - Multimodal: Text, images\n - Performance: Moderate (200-800ms)\n - Cost: Moderate to high ($0.25-$15 per 1M tokens)\n - Use when: Need long context or complex reasoning\n\nExamples:\n - Use OPENAI for production with structured JSON outputs\n - Use GOOGLE for video summarization and cost-sensitive workloads\n - Use ANTHROPIC for complex reasoning with long documents"},"LabelDistributionResponse":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id"},"labels":{"items":{"$ref":"#/components/schemas/LabelMetric"},"type":"array","title":"Labels"},"total_labels":{"type":"integer","title":"Total Labels"}},"type":"object","required":["taxonomy_id","labels","total_labels"],"title":"LabelDistributionResponse","description":"Taxonomy label distribution response."},"LabelMetric":{"properties":{"label":{"type":"string","title":"Label"},"count":{"type":"integer","title":"Count"},"percentage":{"type":"number","title":"Percentage"},"avg_confidence":{"type":"number","title":"Avg Confidence"}},"type":"object","required":["label","count","percentage","avg_confidence"],"title":"LabelMetric","description":"Label distribution metrics."},"LatencyMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket"},"document_count":{"type":"integer","title":"Document Count"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms"},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms"}},"type":"object","required":["time_bucket","document_count","avg_latency_ms","p95_latency_ms","p99_latency_ms"],"title":"LatencyMetric","description":"Latency distribution metric."},"LatencyMetrics":{"properties":{"p50_ms":{"type":"number","minimum":0.0,"title":"P50 Ms","description":"50th percentile latency in milliseconds."},"p90_ms":{"type":"number","minimum":0.0,"title":"P90 Ms","description":"90th percentile latency in milliseconds."},"p99_ms":{"type":"number","minimum":0.0,"title":"P99 Ms","description":"99th percentile latency in milliseconds."},"mean_ms":{"type":"number","minimum":0.0,"title":"Mean Ms","description":"Mean latency in milliseconds."},"stage_latencies":{"additionalProperties":{"type":"number"},"type":"object","title":"Stage Latencies","description":"Per-stage latency breakdown (stage_name -> avg_ms)."}},"type":"object","required":["p50_ms","p90_ms","p99_ms","mean_ms"],"title":"LatencyMetrics","description":"Performance timing statistics for a pipeline."},"LatencyResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__collections__models__TimeRange"},"metrics":{"items":{"$ref":"#/components/schemas/LatencyMetric"},"type":"array","title":"Metrics"},"slowest_documents":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Slowest Documents"}},"type":"object","required":["collection_id","time_range","metrics"],"title":"LatencyResponse","description":"Processing latency distribution."},"LayoutConfig":{"properties":{"mode":{"type":"string","title":"Mode","description":"Display mode for results","default":"grid","examples":["grid","list","masonry"]},"columns":{"type":"integer","maximum":6.0,"minimum":1.0,"title":"Columns","description":"Number of columns for grid/masonry layouts","default":3},"gap":{"type":"string","title":"Gap","description":"Gap between items","default":"16px","examples":["8px","16px","24px"]},"full_width":{"type":"boolean","title":"Full Width","description":"Whether to use full viewport width for the layout (edge-to-edge)","default":false}},"type":"object","title":"LayoutConfig","description":"Layout configuration for search results display."},"LifecycleState":{"type":"string","enum":["active","cold","archived"],"title":"LifecycleState"},"LifecycleStatusResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"lifecycle_state":{"$ref":"#/components/schemas/LifecycleState"},"s3_vector_index":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Vector Index"},"qdrant_document_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Qdrant Document Count"},"s3_vector_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"S3 Vector Count"},"last_transitioned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Transitioned At"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning"}},"type":"object","required":["collection_id","lifecycle_state"],"title":"LifecycleStatusResponse"},"LineageStep":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"Collection ID where this processing step occurred","examples":["col_video_frames","col_scenes","col_embeddings"]},"feature_extractor_id":{"type":"string","title":"Feature Extractor Id","description":"Feature extractor that processed the data in this step","examples":["multimodal_extractor_v1","scene_detector_v1","text_extractor_v1"]},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Document ID from this step (for intermediate steps). Allows tracing back through the decomposition tree.","examples":["doc_frame001","doc_scene005"]},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"When this processing step occurred","examples":["2025-10-18T10:30:00Z"]}},"type":"object","required":["collection_id","feature_extractor_id"],"title":"LineageStep","description":"Single processing step in a document's lineage chain.\n\nEach step represents one transformation in the decomposition tree,\ntracking which collection and feature extractor produced the document.\n\nExample:\n ```python\n step = LineageStep(\n collection_id=\"col_video_frames\",\n feature_extractor_id=\"multimodal_extractor_v1\",\n document_id=\"doc_frame123\",\n timestamp=datetime.now()\n )\n ```","examples":[{"collection_id":"col_video_frames","document_id":"doc_frame123","feature_extractor_id":"multimodal_extractor_v1","timestamp":"2025-10-18T10:30:00Z"}]},"LintResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether the manifest is valid (no errors, warnings OK)"},"results":{"items":{"$ref":"#/components/schemas/LintResult"},"type":"array","title":"Results","description":"List of lint results"},"summary":{"additionalProperties":{"type":"integer"},"type":"object","title":"Summary","description":"Count of results by severity"}},"type":"object","required":["valid"],"title":"LintResponse","description":"Response from the lint endpoint.\n\nExample:\n {\n \"valid\": true,\n \"results\": [...],\n \"summary\": {\"error\": 0, \"warning\": 2, \"info\": 3}\n }","examples":[{"results":[{"code":"UNUSED_COLLECTION","location":"collections[2]","message":"Collection 'orphan_data' is not referenced by any retriever","severity":"warning","suggestion":"Add a retriever that uses this collection or remove it"}],"summary":{"error":0,"info":0,"warning":1},"valid":true}]},"LintResult":{"properties":{"code":{"type":"string","title":"Code","description":"Lint rule code (e.g., 'UNUSED_EXTRACTOR', 'MISSING_CACHE_CONFIG')"},"severity":{"$ref":"#/components/schemas/LintSeverity","description":"Severity level: error, warning, or info"},"message":{"type":"string","title":"Message","description":"Human-readable description of the issue"},"location":{"type":"string","title":"Location","description":"Path to the problematic element (e.g., 'retrievers[0].stages[2]')"},"suggestion":{"type":"string","title":"Suggestion","description":"Actionable suggestion for fixing the issue"},"fix_example":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fix Example","description":"Optional YAML example showing the correct configuration"}},"type":"object","required":["code","severity","message","location","suggestion"],"title":"LintResult","description":"A single lint result with actionable suggestion.\n\nExample:\n {\n \"code\": \"UNUSED_EXTRACTOR\",\n \"severity\": \"warning\",\n \"message\": \"Feature extractor 'text_extractor' in namespace 'my_ns' is not used by any collection\",\n \"location\": \"namespaces[0].feature_extractors[1]\",\n \"suggestion\": \"Remove the unused extractor or add a collection that uses it\",\n \"fix_example\": \"collections:\\n - name: text_docs\\n feature_extractor:\\n name: text_extractor\"\n }","examples":[{"code":"MISSING_CACHE_CONFIG","fix_example":"cache_config:\n enabled: true\n ttl_seconds: 3600","location":"retrievers[0]","message":"Retriever 'product_search' has no cache configuration","severity":"info","suggestion":"Add cache_config to improve performance for repeated queries"}]},"LintSeverity":{"type":"string","enum":["error","warning","info"],"title":"LintSeverity","description":"Severity level for lint results."},"ListAdhocExecutionsRequest":{"properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Filter by execution status. Common values: 'completed', 'failed'. OPTIONAL - omit to see all statuses.","examples":["completed","failed"]},"start_time":{"anyOf":[{},{"type":"null"}],"title":"Start Time","description":"Filter executions after this timestamp (inclusive). OPTIONAL - omit for no start time filter."},"end_time":{"anyOf":[{},{"type":"null"}],"title":"End Time","description":"Filter executions before this timestamp (inclusive). OPTIONAL - omit for no end time filter."}},"type":"object","title":"ListAdhocExecutionsRequest","description":"Request to list ad-hoc retriever executions with filtering.\n\nAllows filtering by status, time range, and searching by query summary.\nResults are ordered by timestamp descending (most recent first)."},"ListAdhocExecutionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AdhocExecutionSummary"},"type":"array","title":"Results","description":"List of ad-hoc execution summaries."},"total":{"type":"integer","title":"Total","description":"Total number of ad-hoc executions matching filters.","default":0},"pagination":{"title":"Pagination","description":"Pagination metadata."}},"type":"object","required":["pagination"],"title":"ListAdhocExecutionsResponse","description":"Response from listing ad-hoc retriever executions."},"ListAlertsRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across alert_id, name, description"},"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply to the alert list"},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort configuration for the alert list"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false}},"type":"object","title":"ListAlertsRequest","description":"Request model to list alerts."},"ListAlertsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AlertResponse"},"type":"array","title":"Results","description":"List of alerts"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of alerts matching query"},"stats":{"anyOf":[{"$ref":"#/components/schemas/AlertListStats"},{"type":"null"}],"description":"Aggregate statistics across all alerts in the result"}},"type":"object","required":["results","pagination","total_count"],"title":"ListAlertsResponse","description":"Response model for listing alerts."},"ListBatchesRequest":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"Filter batches by status."},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Filter batches to only those associated with a specific collection ID. Useful for tracking the processing state of all batches for a given collection."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"The number of batches to skip.","default":0},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"The maximum number of batches to return.","default":100}},"type":"object","title":"ListBatchesRequest","description":"The request model for listing batches."},"ListBatchesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BatchModel"},"type":"array","title":"Results","description":"A list of batches."},"total_count":{"type":"integer","title":"Total Count","description":"The total number of batches found."}},"type":"object","required":["results","total_count"],"title":"ListBatchesResponse","description":"The response model for listing batches."},"ListBucketsRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across bucket_id, bucket_name, description, and other text fields"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Filters to apply to the bucket list. Supports filtering by bucket_id or bucket_name."},"sort":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sort","description":"Sort options for the bucket list"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Number of results to return","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of results to skip","default":0}},"type":"object","title":"ListBucketsRequest","description":"Request model for listing buckets."},"ListBucketsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BucketResponse"},"type":"array","title":"Results"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of buckets matching the query"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"stats":{"anyOf":[{"$ref":"#/components/schemas/BucketListStats"},{"type":"null"}],"description":"Aggregate statistics across all buckets in the result"}},"type":"object","required":["results","total_count","pagination"],"title":"ListBucketsResponse","description":"Response model for listing buckets."},"ListClusterExecutionsRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"OPTIONAL. Complex filtering conditions for execution history. NOT REQUIRED - omit to return all executions. Structure: Logical operator (AND/OR) with array of conditions. Supported filter fields: - status: Filter by execution status (pending/processing/completed/failed). - created_at: Filter by execution start date (use gte/lte for ranges). - num_clusters: Filter by number of clusters found. - metrics.silhouette_score: Filter by quality threshold. Example filters: - Status is completed: {operator: 'AND', conditions: [{field: 'status', value: 'completed', operator: '=='}]}. - Created in last 7 days: {operator: 'AND', conditions: [{field: 'created_at', operator: 'gte', value: '2025-11-06T00:00:00Z'}]}. - Good quality (silhouette > 0.5): {operator: 'AND', conditions: [{field: 'metrics.silhouette_score', operator: '>', value: 0.5}]}. Combine with OR: Status completed OR failed (exclude in-progress)."},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"OPTIONAL. Sorting configuration for results. NOT REQUIRED - defaults to created_at descending (newest first). Structure: {field: 'field_name', direction: 'asc' or 'desc'}. Sortable fields: - created_at: Sort by execution start time (default). - completed_at: Sort by execution finish time. - num_clusters: Sort by cluster count. - num_points: Sort by document count. - metrics.silhouette_score: Sort by quality score. - status: Sort by execution status. Common use cases: - Newest first (default): {field: 'created_at', direction: 'desc'}. - Best quality first: {field: 'metrics.silhouette_score', direction: 'desc'}. - Failed executions first: {field: 'status', direction: 'asc'} (alphabetical)."},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"OPTIONAL. Full-text search query across execution metadata. NOT REQUIRED - omit for no search filtering. Searches in: - run_id: Search by execution identifier. - error_message: Find executions with specific error text. - centroids.label: Search by cluster label names. - centroids.summary: Search by cluster descriptions. Behavior: - Case-insensitive partial matching. - Multiple terms are AND-ed together. - Combines with filters for complex queries. Examples: - 'failed' ā†’ Find executions with 'failed' in error messages. - 'product review' ā†’ Find executions with clusters about products/reviews. - 'run_abc123' ā†’ Find specific execution by ID.","examples":["failed","product review","insufficient documents","run_abc123"]}},"type":"object","title":"ListClusterExecutionsRequest","description":"Request parameters for listing and filtering cluster execution history.\n\nProvides flexible querying of historical clustering executions with filtering,\nsorting, and search capabilities. Use to build execution history UIs, compare\nruns over time, and analyze clustering performance trends.\n\nUse Cases:\n - Display execution history table with sorting and filtering\n - Find failed executions for debugging\n - Compare metrics across successful runs\n - Search executions by date range or status\n - Build execution timeline visualization\n\nQuery Behavior:\n - Empty request {} returns all executions sorted by created_at (newest first)\n - Filters, sort, and search can be combined for complex queries\n - Results are paginated (use page/page_size query params)\n\nNote:\n All fields are OPTIONAL. Omit for default behavior (all executions, newest first).","examples":[{"description":"Get all executions (default behavior)"},{"description":"Get only completed executions","filters":{"conditions":[{"field":"status","operator":"==","value":"completed"}],"operator":"AND"}},{"description":"Get failed executions in last 7 days, sorted by date","filters":{"conditions":[{"field":"status","operator":"==","value":"failed"},{"field":"created_at","operator":"gte","value":"2025-11-06T00:00:00Z"}],"operator":"AND"},"sort":{"direction":"desc","field":"created_at"}},{"description":"Get high-quality executions (silhouette > 0.7)","filters":{"conditions":[{"field":"metrics.silhouette_score","operator":">","value":0.7}],"operator":"AND"},"sort":{"direction":"desc","field":"metrics.silhouette_score"}},{"description":"Search executions mentioning 'product'","search":"product","sort":{"direction":"desc","field":"created_at"}}]},"ListClusterExecutionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ClusterExecutionResult"},"type":"array","title":"Results","description":"REQUIRED. Array of cluster execution results for the current page. Length: 0 to page_size (default 10, max typically 100). Empty array [] if: - No executions exist for this cluster. - Filters matched no results. - Requested page beyond available pages. Sorted by: created_at descending (newest first) by default. Override with sort parameter in request. Each item contains: - run_id: Unique execution identifier. - status: pending/processing/completed/failed. - num_clusters: Clusters found. - metrics: Quality scores (if available). - centroids: Cluster labels and summaries (if available). - created_at/completed_at: Timestamps. - error_message: Error details (if failed). Use for: Rendering execution history table rows."},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"REQUIRED. Pagination metadata for navigating result pages. Contains: - total: Total items across all pages (same as total_count). - page: Current page number (1-indexed). - page_size: Items per page. - total_pages: Total number of pages. - next_page: URL for next page (null if last page). - previous_page: URL for previous page (null if first page). Use for: - Pagination controls ('Page 2 of 5'). - Next/Previous buttons (check null for disabled state). - Showing X-Y of Z results calculations."},"total_count":{"type":"integer","minimum":0.0,"title":"Total Count","description":"REQUIRED. Total number of executions matching the query across ALL pages. Use for: - Display total count ('Found 127 executions'). - Calculate pagination ('Showing 1-10 of 127'). - Validate filters (0 = no matches, refine query). Behavior: - Includes all filtered results, not just current page. - Changes when filters are applied. - Equals len(results) only if all results fit on one page. Example: - Query returns 127 executions total. - Page size = 10. - Current page (1) shows results[0:10]. - total_count = 127 (not 10).","examples":[127,50,10,0]},"stats":{"anyOf":[{"$ref":"#/components/schemas/ClusterExecutionListStats"},{"type":"null"}],"description":"OPTIONAL. Aggregate statistics for executions in current result set. NOT REQUIRED - may be null if stats calculation disabled. Typically always provided for execution listing. Contains: - total_executions: Count in current page. - executions_by_status: Status distribution {'completed': 45, 'failed': 3}. - avg_execution_time_ms: Mean duration. - total_documents_clustered: Sum of all processed documents. - avg_num_clusters: Mean clusters per execution. Use for: - Summary cards above table. - Status pie chart. - Performance metrics dashboard. Note: - Stats calculated for current page only (or all if no pagination). - Respects filters (stats for filtered subset)."}},"type":"object","required":["results","pagination","total_count"],"title":"ListClusterExecutionsResponse","description":"Complete response for cluster execution history listing endpoint.\n\nReturns paginated execution history with filtering, sorting, and aggregate statistics.\nUse to build execution history UIs, monitoring dashboards, and performance analytics.\n\nResponse Structure:\n - results: Array of execution details (paginated)\n - pagination: Page navigation info (current page, total pages, etc.)\n - total_count: Total matching executions (across all pages)\n - stats: Aggregated metrics for current result set\n\nUse Cases:\n - Build execution history table with pagination\n - Display execution status dashboard with charts\n - Monitor clustering performance trends\n - Debug failed executions\n - Compare quality metrics across runs\n\nPagination Behavior:\n - Default: 10 executions per page\n - Use query params: ?page=1&page_size=20\n - results contains current page only\n - total_count shows all matching executions\n - pagination provides navigation links\n\nExample Workflow:\n 1. Request: POST /clusters/{id}/executions/list with filters\n 2. Response: 50 total executions, showing page 1 (10 results)\n 3. Display: Show 10 results + \"Page 1 of 5\" + aggregate stats\n 4. Navigate: Use pagination.next_page for next 10 results","examples":[{"description":"Typical paginated response with executions","pagination":{"next_page":"/clusters/clust_xyz/executions/list?page=2","page":1,"page_size":10,"total":127,"total_pages":13},"results":[{"centroids":[{"cluster_id":"cl_0","label":"Product Reviews","num_members":45}],"cluster_id":"clust_ae3e28a429","completed_at":"2025-11-13T13:25:40.122000Z","created_at":"2025-11-13T13:20:40.122000Z","metrics":{"silhouette_score":0.85},"num_clusters":3,"num_points":100,"run_id":"run_a8e270953254754b","status":"completed"}],"stats":{"avg_execution_time_ms":8234.5,"avg_num_clusters":5.2,"executions_by_status":{"completed":8,"failed":2},"total_documents_clustered":1000,"total_executions":10},"total_count":127},{"description":"Empty result (no executions found)","pagination":{"page":1,"page_size":10,"total":0,"total_pages":0},"results":[],"stats":{"avg_execution_time_ms":0.0,"avg_num_clusters":0.0,"executions_by_status":{},"total_documents_clustered":0,"total_executions":0},"total_count":0},{"description":"Last page of results (10 total, 3 on last page)","pagination":{"page":2,"page_size":5,"previous_page":"/clusters/clust_xyz/executions/list?page=1","total":10,"total_pages":2},"results":[{"cluster_id":"clust_abc123","completed_at":"2025-11-13T12:05:00.000000Z","created_at":"2025-11-13T12:00:00.000000Z","num_clusters":5,"num_points":200,"run_id":"run_xyz789","status":"completed"}],"stats":{"avg_execution_time_ms":12000.0,"avg_num_clusters":5.0,"executions_by_status":{"completed":3},"total_documents_clustered":600,"total_executions":3},"total_count":10}]},"ListClustersRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply when listing clusters"},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options for the results"},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across cluster_id, cluster_name, description, and other text fields"}},"type":"object","title":"ListClustersRequest","description":"Request model for listing clusters."},"ListClustersResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ClusterMetadata"},"type":"array","title":"Results","description":"List of cluster metadata"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of clusters matching the query"},"stats":{"anyOf":[{"$ref":"#/components/schemas/ClusterListStats"},{"type":"null"}],"description":"Aggregate statistics across all clusters in the result"}},"type":"object","required":["results","pagination","total_count"],"title":"ListClustersResponse","description":"Response model for listing clusters."},"ListCollectionsRequest":{"properties":{"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Filters to apply when listing collections. Supports nested field filtering like 'taxonomy_applications.taxonomy_id'. Format: {\"AND\": [{\"field\": \"field_name\", \"operator\": \"eq\", \"value\": \"value\"}]}"},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options for the results"},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across collection_id, collection_name, description, and other text fields"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false}},"type":"object","title":"ListCollectionsRequest","description":"Request model for listing collections.\n\nTo filter by taxonomy, use dot notation in filters:\nfilters.AND = [{\"field\": \"taxonomy_applications.taxonomy_id\", \"operator\": \"eq\", \"value\": \"tax_123\"}]"},"ListCollectionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/CollectionResponse"},"type":"array","title":"Results","description":"List of collections"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of collections matching the query"},"stats":{"anyOf":[{"$ref":"#/components/schemas/CollectionListStats"},{"type":"null"}],"description":"Aggregate statistics across all collections in the result"}},"type":"object","required":["results","pagination","total_count"],"title":"ListCollectionsResponse","description":"Response model for listing collections."},"ListDocumentsRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply."},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options."},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"OPTIONAL cursor for efficient deep pagination. Pass the 'pagination.next_cursor' value from a previous response to fetch the next page. When cursor is provided, the page/offset query params are ignored. Use cursor-based pagination when: (1) paginating beyond page ~100, (2) sorting large datasets, or (3) you need consistent iteration. Use offset-based pagination (default) for: simple use cases, random page access, or when page numbers are needed in the UI."},"return_presigned_urls":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Return Presigned Urls","description":"Whether to return presigned URLs for object keys.","default":false},"return_vectors":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Return Vectors","description":"Whether to return vector embeddings in the document results.","default":false},"return_vector_names":{"anyOf":[{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Return Vector Names","description":"Controls vector data in the response. Pass `true` to get a `_vectors` field listing available vector names (no embedding data). Pass a list of vector names (e.g. `[\"fashionsiglip_v1_embedding\"]`) to return the actual float arrays for those specific vectors, keyed by name.","default":false},"group_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group By","description":"OPTIONAL. Field to group documents by. Supports dot notation for nested fields (e.g., 'metadata.category', 'source_type'). When specified, documents are grouped by the field value and returned as grouped results. Requires a payload index on the field in Qdrant for optimal performance. If no index exists, the operation will fail with a validation error. Common groupable fields: 'source_object_id', 'root_object_id', 'collection_id', 'metadata.category'.","examples":["source_object_id","metadata.category","root_object_id","source_type"]},"select":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Select","description":"OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'content'). When specified, only the selected fields will be returned in the document results, reducing response size. System fields like '_id' and 'document_id' are always included. Use this to optimize response size when working with large documents.","examples":[["metadata.title","content"],["document_id","metadata"],["source_type","created_at"]]},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Number of documents to return per page.","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of documents to skip (offset-based pagination).","default":0}},"type":"object","title":"ListDocumentsRequest","description":"Request model for listing documents.\n\nSupports two pagination strategies:\n\n**Offset-based (default)**: Use query params `?page=2&page_size=10`\n- Simple and familiar\n- Works well for shallow pagination (first ~100 pages)\n- Less efficient for deep pagination with sorting\n\n**Cursor-based (optional)**: Pass `cursor` from previous response's `next_cursor`\n- More efficient for deep pagination (page 100+)\n- Required for consistent results when sorting large datasets\n- When cursor is provided, offset is ignored"},"ListDocumentsResponse":{"properties":{"results":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array"},{"type":"null"}],"title":"Results","description":"List of documents when group_by is NOT specified. Contains flat list of documents with pagination applied. Mutually exclusive with 'groups' field."},"groups":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentGroup"},"type":"array"},{"type":"null"}],"title":"Groups","description":"List of document groups when group_by IS specified. Each group contains documents sharing the same field value. Pagination applies to groups, not individual documents. Mutually exclusive with 'results' field."},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information. Includes next_cursor for cursor-based pagination. When group_by is used, pagination applies to groups (not individual documents). total_count reflects total number of groups, not total documents."},"total_documents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Documents","description":"Total number of documents matching the query (across all pages). Alias for stats.total_documents ā€” included at the top level for convenience."},"stats":{"anyOf":[{"$ref":"#/components/schemas/DocumentListStats"},{"type":"null"}],"description":"Aggregate statistics across all documents in the result"},"group_by_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group By Field","description":"The field that was used for grouping when group_by was specified. None for non-grouped results. Useful for clients to understand the grouping structure.","examples":["source_object_id","metadata.category"]}},"type":"object","required":["pagination"],"title":"ListDocumentsResponse","description":"Response model for listing documents.\n\nSupports both regular document lists and grouped results based on the group_by parameter.\nWhen group_by is specified, results are returned as groups instead of a flat list.\n\nPagination strategies:\n- **Offset-based (default)**: Use `pagination.page` and `pagination.page_size`\n- **Cursor-based (optional)**: Use `pagination.next_cursor` for efficient deep pagination","examples":[{"description":"Regular document list (no grouping)","pagination":{"has_more":false,"limit":10,"offset":0,"total_count":1},"results":[{"collection_id":"col_articles","document_id":"doc_123","metadata":{"title":"AI Article"}}],"stats":{"avg_blobs_per_document":1.0,"total_documents":1}},{"description":"Grouped document list (group_by specified)","group_by_field":"source_object_id","groups":[{"count":2,"documents":[{"collection_id":"col_frames","document_id":"doc_frame_001","source_object_id":"obj_video123"},{"collection_id":"col_frames","document_id":"doc_frame_002","source_object_id":"obj_video123"}],"group_key":"obj_video123"}],"pagination":{"has_more":false,"limit":10,"offset":0,"total_count":1},"stats":{"avg_blobs_per_document":1.0,"avg_documents_per_group":2.0,"total_documents":2,"total_groups":1}}]},"ListExecutionsRequest":{"properties":{"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters"},"sorts":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sorts"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Optional status filter (completed, failed, running)."}},"type":"object","title":"ListExecutionsRequest","description":"Request to list retriever executions."},"ListExecutionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/RetrieverExecutionSummary"},"type":"array","title":"Results","description":"Execution summaries"},"pagination":{"$ref":"#/components/schemas/PaginationMetadata","description":"Pagination metadata"}},"type":"object","required":["pagination"],"title":"ListExecutionsResponse","description":"Re-export shared execution listing response for OpenAPI docs."},"ListFoldersResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/FolderItem"},"type":"array","title":"Results","description":"List of folders found at the specified parent path. Only includes folders (not files). Empty list if no folders found or path doesn't exist."},"parent_path":{"type":"string","title":"Parent Path","description":"The parent folder path that was queried. This is the path specified in the request (or '/' for root). Use this to show breadcrumb navigation in UI.","examples":["/","/Marketing","/Marketing/2024 Campaigns"]}},"type":"object","required":["results","parent_path"],"title":"ListFoldersResponse","description":"Response payload for listing Google Drive folders.\n\nReturns a list of folders available at the specified path, enabling users\nto browse and select folders for sync configuration.","examples":[{"description":"List of folders at root","folders":[{"id":"0AH-Xabc123","mime_type":"application/vnd.google-apps.folder","name":"Marketing","path":"/Marketing"},{"id":"0AH-Xdef456","mime_type":"application/vnd.google-apps.folder","name":"Sales","path":"/Sales"}],"parent_path":"/"}]},"ListInteractionsRequest":{"properties":{"execution_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Id","description":"Filter by retriever execution ID. Most common query: find all interactions from a specific search execution. Example: 'exec_abc123'","examples":["exec_abc123","exec_550e8400e29b"]},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Filter by retriever ID. Compare performance across different retriever configurations. Example: 'ret_product_search_v2'","examples":["ret_product_search","ret_baseline_v1"]},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Filter by session ID. Track user journey across multiple searches within a session. Example: 'sess_xyz789'","examples":["sess_abc123","sess_xyz789_1234567890"]},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Filter by user ID. Analyze behavior of specific users for personalization insights. Example: 'user_456'","examples":["user_abc123","customer_456"]},"feature_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Id","description":"Filter by feature/document ID. Find all interactions with a specific document across all searches. Example: 'doc_abc123'","examples":["doc_abc123","prod_xyz789"]},"interaction_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interaction Type","description":"Filter by interaction type. Use to find specific behaviors like clicks, purchases, or feedback. Example: 'click', 'positive_feedback'","examples":["click","positive_feedback","purchase"]},"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Advanced filters using LogicalOperator for complex analytics queries. Supports shorthand syntax and complex AND/OR/NOT logic. Use this for: range queries, complex conditions, metadata filtering. Examples: - Position range: {'position': {'lte': 5}} - Time range: {'timestamp': {'gte': '2025-01-01'}} - Complex: {'AND': [{'field': 'position', 'operator': 'lte', 'value': 5}, {'field': 'interaction_type', 'operator': 'in', 'value': ['click', 'purchase']}]} See LogicalOperator documentation for full syntax.","examples":[{"position":{"lte":5}},{"AND":[{"field":"position","operator":"lte","value":5},{"field":"interaction_type","operator":"in","value":["click","purchase"]}]},{"OR":[{"field":"interaction_type","operator":"eq","value":"purchase"},{"field":"metadata.duration_ms","operator":"gte","value":10000}]}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options for ordering results. Default: timestamp descending (newest first). Examples: - Sort by timestamp: {'field': 'timestamp', 'direction': 'desc'} - Sort by position: {'field': 'position', 'direction': 'asc'}","examples":[{"direction":"desc","field":"timestamp"},{"direction":"asc","field":"position"}]},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Full-text search across metadata fields. NOT REQUIRED. Use to search interaction metadata content.","examples":["mobile device","campaign_summer_2024"]}},"type":"object","title":"ListInteractionsRequest","description":"Request for listing interactions with filters.\n\nSupports both simple field filters (for common queries) and advanced\nLogicalOperator filters (for complex analytics). This hybrid approach\nfollows the same pattern as the Tasks module.\n\nCommon Queries (Simple Fields):\n - Filter by execution: {\"execution_id\": \"exec_abc\"}\n - Filter by session: {\"session_id\": \"sess_xyz\"}\n - Filter by user: {\"user_id\": \"user_123\"}\n\nAdvanced Queries (LogicalOperator):\n - Range queries: {\"filters\": {\"position\": {\"lte\": 5}}}\n - Complex logic: {\"filters\": {\"AND\": [...]}}\n - Time ranges: {\"filters\": {\"created_at\": {\"gte\": \"2025-01-01\"}}}"},"ListInteractionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/InteractionResponse"},"type":"array","title":"Results","description":"List of interactions matching the query filters"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information for navigating result pages"}},"type":"object","required":["results","pagination"],"title":"ListInteractionsResponse","description":"Response for listing interactions with pagination.\n\nReturns a paginated list of interaction records matching the query filters."},"ListMigrationsRequest":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/MigrationStatus"},{"type":"null"}],"description":"Filter by status"},"migration_type":{"anyOf":[{"$ref":"#/components/schemas/MigrationType"},{"type":"null"}],"description":"Filter by type"},"source_namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Namespace Id","description":"Filter by source namespace"},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Maximum results","default":20},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Result offset for pagination","default":0}},"type":"object","title":"ListMigrationsRequest","description":"Request to list migrations with filters."},"ListMigrationsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/GetMigrationResponse"},"type":"array","title":"Results","description":"List of migrations"},"total":{"type":"integer","title":"Total","description":"Total count matching filters"},"limit":{"type":"integer","title":"Limit","description":"Results limit"},"offset":{"type":"integer","title":"Offset","description":"Results offset"}},"type":"object","required":["results","total","limit","offset"],"title":"ListMigrationsResponse","description":"Response for listing migrations."},"ListNamespacesRequest":{"properties":{"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Optional filters to apply to the namespace list. Supports filtering by namespace_id or namespace_name.","example":{"namespace_id":"ns_abc123","namespace_name":{"$regex":"^my_namespace"}}},"sort":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sort","description":"Optional sort criteria for the namespace list.","example":{"direction":"asc","field":"namespace_name"}},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across namespace_id, namespace_name, description, and other text fields.","example":"ns_abc123"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false}},"type":"object","title":"ListNamespacesRequest","description":"Request schema for listing namespaces.","examples":[{"filters":{"namespace_id":"ns_abc123"},"sort":{"direction":"asc","field":"namespace_name"}},{"search":"ns_abc123"}]},"ListNamespacesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/NamespaceModel"},"type":"array","title":"Results","description":"List of namespaces matching the query"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information for the current result window"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of namespaces that match the query"},"stats":{"anyOf":[{"$ref":"#/components/schemas/NamespaceListStats"},{"type":"null"}],"description":"Aggregate statistics across all namespaces in the result"}},"type":"object","required":["results","pagination","total_count"],"title":"ListNamespacesResponse","description":"Response schema for listing namespaces.","examples":[{"pagination":{"has_more":false,"limit":10,"skip":0},"results":[{"created_at":"2024-01-15T10:30:00Z","description":"This namespace contains playlists from Spotify","feature_extractors":[{"feature_extractor_name":"multimodal_extractor","version":"v1"},{"feature_extractor_name":"image_extractor","params":{"model":"siglip_base"},"version":"v1"}],"namespace_id":"ns_ab12cd34ef","namespace_name":"spotify_playlists_dev","payload_indexes":[{"field_name":"metadata.title","type":"text"}],"updated_at":"2024-01-15T10:30:00Z"}],"total_count":1}]},"ListNotificationsRequest":{"properties":{"notification_type":{"anyOf":[{"$ref":"#/components/schemas/NotificationType"},{"type":"null"}],"description":"Filter by notification type"},"priority":{"anyOf":[{"$ref":"#/components/schemas/NotificationPriority"},{"type":"null"}],"description":"Filter by priority"},"read":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Read","description":"Filter by read status"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Filter by user ID"}},"type":"object","title":"ListNotificationsRequest","description":"Request model for listing notifications."},"ListNotificationsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/Notification"},"type":"array","title":"Results","description":"List of notifications"},"pagination":{"additionalProperties":true,"type":"object","title":"Pagination","description":"Pagination information"},"total":{"type":"integer","title":"Total","description":"Total number of notifications"}},"type":"object","required":["results","pagination","total"],"title":"ListNotificationsResponse","description":"Response model for listing notifications."},"ListObjectsRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply to the object list"},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options for the object list"},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term to filter objects by key or metadata"},"select":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Select","description":"OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'status'). When specified, only the selected fields will be returned in the object results, reducing response size. System fields like 'object_id' and 'bucket_id' are always included. Use this to optimize response size when working with large objects.","examples":[["metadata","status","created_at"],["object_id","file_extension","size"],["metadata.title","content_type"]]}},"type":"object","title":"ListObjectsRequest","description":"Request model for listing objects in a bucket."},"ListObjectsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ObjectResponse"},"type":"array","title":"Results","description":"List of objects matching the query"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information"},"stats":{"anyOf":[{"$ref":"#/components/schemas/ObjectListStats"},{"type":"null"}],"description":"Aggregate statistics across all objects in the result"}},"type":"object","required":["results","pagination"],"title":"ListObjectsResponse","description":"Response model for listing objects in a bucket.","examples":[{"pagination":{"has_more":false,"limit":10,"skip":0},"results":[{"blobs":[],"bucket_id":"bkt_9xy8z7","created_at":"2024-10-21T10:30:00Z","key_prefix":"/contract-2024","metadata":{"category":"contracts","year":2024},"object_id":"obj_123abc456def","status":"DRAFT","updated_at":"2024-10-21T10:30:00Z"}]}]},"ListPagesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PageResponse"},"type":"array","title":"Results"},"total_count":{"type":"integer","title":"Total Count"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["results","total_count","limit","offset"],"title":"ListPagesResponse","description":"Paginated list of pages."},"ListPublicRetrieversResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PublicRetrieverListItem"},"type":"array","title":"Results","description":"List of public retrievers"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of public retrievers matching the query"},"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Results per page"},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages"},"stats":{"anyOf":[{"$ref":"#/components/schemas/PublicRetrieverListStats"},{"type":"null"}],"description":"Aggregate statistics across all public retrievers"}},"type":"object","required":["results","total_count","page","page_size","total_pages"],"title":"ListPublicRetrieversResponse","description":"Response for listing public retrievers.\n\nFollows the same pattern as ListCollectionsResponse for consistent developer experience."},"ListRetrieversRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across retriever_id, retriever_name, description, and other text fields"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Filters to apply to the retriever list. Supports filtering by retriever_id or retriever_name."},"sorts":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sorts","description":"Sort options for the retriever list"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false}},"type":"object","title":"ListRetrieversRequest","description":"Request to list retrievers."},"ListRetrieversResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/RetrieverModel-Output"},"type":"array","title":"Results","description":"List of retrievers in the namespace."},"total":{"type":"integer","title":"Total","description":"Total number of retrievers.","default":0}},"type":"object","title":"ListRetrieversResponse","description":"Response from listing retrievers."},"ListSessionsRequest":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/SessionStatus"},{"type":"null"}],"description":"Filter by session status"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Additional filters"},"sort":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sort","description":"Sort configuration"}},"type":"object","title":"ListSessionsRequest","description":"Request payload for listing sessions.\n\nAttributes:\n status: Optional status filter\n filters: Optional additional filters\n sort: Optional sort configuration\n\nExample:\n ```python\n request = ListSessionsRequest(\n status=\"active\",\n filters={\"user_id\": \"user_123\"}\n )\n ```"},"ListSessionsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/GetSessionResponse"},"type":"array","title":"Results","description":"Session list"},"total":{"type":"integer","title":"Total","description":"Total matching sessions"},"pagination":{"additionalProperties":true,"type":"object","title":"Pagination","description":"Pagination information"}},"type":"object","required":["results","total","pagination"],"title":"ListSessionsResponse","description":"Response for listing sessions.\n\nAttributes:\n results: List of session summaries\n total: Total number of sessions matching query\n pagination: Pagination information\n\nExample:\n ```python\n response = ListSessionsResponse(\n results=[...],\n total=50,\n pagination={...}\n )\n ```"},"ListStorageConnectionsRequest":{"properties":{"provider_type":{"anyOf":[{"$ref":"#/components/schemas/StorageProvider"},{"type":"null"}],"description":"OPTIONAL. Filter connections by provider type. Supported: google_drive, s3, snowflake, sharepoint, tigris. If not provided, returns connections of all types.","examples":["google_drive","s3","snowflake","sharepoint","tigris"]},"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"OPTIONAL. Filter connections by operational status. ACTIVE: Healthy and ready for use. SUSPENDED: Temporarily disabled. FAILED: Health checks failing. ARCHIVED: Permanently retired."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"OPTIONAL. Filter by active flag. True: Returns only active connections (status=ACTIVE). False: Returns only inactive connections (SUSPENDED/FAILED/ARCHIVED). If not provided, returns connections of all active states."}},"type":"object","title":"ListStorageConnectionsRequest","description":"Request payload for listing storage connections with filters.\n\nUse this to filter connections by provider type, status, or active flag.\nResults are paginated automatically.\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**Examples:**\n```python\n# List all active Google Drive connections\n{\n \"provider_type\": \"google_drive\",\n \"is_active\": True\n}\n\n# Find failed connections\n{\n \"status\": \"failed\"\n}\n```","examples":[{"description":"List active Google Drive connections","is_active":true,"provider_type":"google_drive"},{"description":"Find failed connections","status":"failed"},{"description":"List all connections (no filters)"}]},"ListSyncConfigurationsRequest":{"properties":{"connection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connection Id","description":"Filter sync configurations by connection ID. NOT REQUIRED. When provided, only returns syncs using this connection. Useful for managing syncs across multiple storage providers. Example: 'conn_abc123'","examples":["conn_abc123","conn_s3_prod"]},"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"Filter sync configurations by status. NOT REQUIRED. Valid values: 'pending', 'processing', 'completed', 'failed', 'paused'. Useful for finding syncs that need attention or monitoring. Example: 'failed' to find syncs with errors.","examples":["pending","processing","failed"]},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Filter sync configurations by active status. NOT REQUIRED. True: Only active syncs that are currently monitoring/processing. False: Only paused/disabled syncs. Omit to include both active and inactive.","examples":[true,false]}},"type":"object","title":"ListSyncConfigurationsRequest","description":"Request to filter sync configurations for listing.\n\nAll filters are optional - when omitted, returns all sync configurations\nfor the bucket. Multiple filters can be combined for precise queries.\n\nUse Cases:\n - Find all syncs for a specific connection\n - List only active or paused syncs\n - Filter by status to find failed syncs\n\nRequirements:\n - All fields are OPTIONAL\n - Multiple filters are combined with AND logic\n - Empty request returns all configurations","examples":[{"description":"List all configurations (no filters)"},{"description":"Find active syncs only","is_active":true},{"connection_id":"conn_s3_prod","description":"Find failed syncs for a specific connection","status":"failed"},{"description":"Find paused syncs","is_active":false}]},"ListTasksRequest":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"Filter by specific task status (PENDING, IN_PROGRESS, PROCESSING, COMPLETED, FAILED, CANCELED, etc.)."},"task_type":{"anyOf":[{"$ref":"#/components/schemas/TaskType"},{"type":"null"}],"description":"Filter by task type (e.g., API_BUCKETS_OBJECTS_CREATE, BATCH_CONFIRM, etc.)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Advanced filters to apply."},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options."},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term."}},"type":"object","title":"ListTasksRequest","description":"Request model for listing tasks.\n\nFilter tasks by status, type, or other criteria."},"ListTasksResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/TaskResponse"},"type":"array","title":"Results"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}},"type":"object","required":["results","pagination"],"title":"ListTasksResponse","description":"Response model for listing tasks."},"ListTaxonomiesRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across taxonomy_id, taxonomy_name, description, and other text fields"},"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply to the taxonomy list. Supports filtering by taxonomy_id or taxonomy_name."},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort configuration for the taxonomy list"},"case_sensitive":{"type":"boolean","title":"Case Sensitive","description":"If True, filters and search will be case-sensitive","default":false}},"type":"object","title":"ListTaxonomiesRequest","description":"Request model to list taxonomies."},"ListTaxonomiesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/TaxonomyResponse"},"type":"array","title":"Results"},"pagination":{"additionalProperties":true,"type":"object","title":"Pagination"},"total_count":{"type":"integer","title":"Total Count"},"stats":{"anyOf":[{"$ref":"#/components/schemas/TaxonomyListStats"},{"type":"null"}],"description":"Aggregate statistics across all taxonomies in the result"}},"type":"object","required":["results","pagination","total_count"],"title":"ListTaxonomiesResponse","description":"Response model for listing taxonomies."},"ListTemplatesRequest":{"properties":{"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Filters to apply when listing templates. Format: {\"AND\": [{\"field\": \"field_name\", \"operator\": \"eq\", \"value\": \"value\"}]}"},"sort":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Sort","description":"Sort options for the results. Format: {'field': 'name', 'direction': 'asc'}"},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search term for wildcard search across template_id, name, description, and tags"},"scope":{"anyOf":[{"$ref":"#/components/schemas/TemplateScope"},{"type":"null"}],"description":"Filter by scope (system, organization, or user)"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Filter by category"},"is_active":{"type":"boolean","title":"Is Active","description":"Show only active templates","default":true},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Filter by tags (templates must have ALL specified tags)"}},"type":"object","title":"ListTemplatesRequest","description":"Request model for listing templates.\n\nProvides the same filtering, sorting, and search capabilities as other\nlist operations (list collections, list buckets, etc.).","examples":[{"category":"semantic_search","is_active":true,"scope":"system","search":"semantic"},{"filters":{"AND":[{"field":"category","operator":"eq","value":"advanced_search"}]},"sort":{"direction":"asc","field":"name"}}]},"ListTemplatesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BaseTemplateModel"},"type":"array","title":"Results","description":"List of templates"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of templates matching the query"}},"type":"object","required":["results","total_count"],"title":"ListTemplatesResponse","description":"Response model for listing templates.","examples":[{"results":[{"category":"semantic_search","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"}],"total_count":1}]},"ListToolsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ToolInfo"},"type":"array","title":"Results","description":"Available tools"},"total":{"type":"integer","title":"Total","description":"Total number of tools"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories","description":"Unique tool categories"}},"type":"object","required":["results","total","categories"],"title":"ListToolsResponse","description":"Response for listing available agent tools.\n\nUse this endpoint to discover available tools before creating a session.\nPass tool names to available_tools in AgentConfig when creating a session.\n\nAttributes:\n results: List of available tools with descriptions\n total: Total number of tools available\n categories: Unique tool categories\n\nExample:\n ```python\n response = ListToolsResponse(\n results=[\n ToolInfo(name=\"smart_search\", description=\"...\", category=\"search\"),\n ToolInfo(name=\"list_collections\", description=\"...\", category=\"read\"),\n ],\n total=25,\n categories=[\"search\", \"read\", \"create\"]\n )\n ```"},"ListUploadsRequest":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Complex filters using logical operators (AND, OR, NOT). Supports shorthand syntax: pass field-value pairs for equality matching. Examples: - Filter by status: {'status': 'PENDING'} - Filter by metadata: {'metadata.campaign': 'summer_2024'} - Complex: {'AND': [{'field': 'status', 'operator': 'eq', 'value': 'PENDING'}, {'field': 'file_size_bytes', 'operator': 'gte', 'value': 1000000}]} See LogicalOperator documentation for full syntax.","examples":[{"status":"PENDING"},{"metadata.campaign":"summer_2024"},{"AND":[{"field":"status","operator":"eq","value":"COMPLETED"},{"field":"created_at","operator":"gte","value":"2024-01-01T00:00:00Z"}]}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/SortOption"},{"type":"null"}],"description":"Sort options for ordering results. Can sort by any field including metadata fields using dot notation. Default: created_at descending (newest first). Examples: - Sort by creation date: {'field': 'created_at', 'direction': 'desc'} - Sort by file size: {'field': 'file_size_bytes', 'direction': 'asc'} - Sort by metadata: {'field': 'metadata.priority', 'direction': 'desc'}","examples":[{"direction":"desc","field":"created_at"},{"direction":"asc","field":"file_size_bytes"},{"direction":"desc","field":"metadata.priority"}]},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Full-text search across filename and metadata fields. Case-insensitive partial matching. Searches in: filename, metadata values (converted to strings). Examples: - 'video' - finds 'product_video.mp4', 'tutorial_video.mov' - 'summer' - finds uploads with metadata.campaign='summer_2024'","examples":["video","summer_2024","profile"]},"return_presigned_urls":{"type":"boolean","title":"Return Presigned Urls","description":"Whether to regenerate presigned URLs for S3 access in the response. OPTIONAL, defaults to false. If true: - Generates new GET presigned URLs for completed uploads - Useful for downloading files from S3 - Adds ~50ms per upload to response time. If false: - No presigned URLs in response - Faster response time. Note: Original PUT presigned URLs are never returned (security).","default":false},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Maximum number of uploads to return. OPTIONAL, defaults to 20.","default":20,"examples":[20,50,100]},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of uploads to skip for pagination. OPTIONAL, defaults to 0.","default":0,"examples":[0,20,100]}},"type":"object","title":"ListUploadsRequest","description":"Request model for listing uploads with filtering, sorting, and search.\n\nProvides flexible querying capabilities using the same filter/sort framework\nas documents, objects, and other list endpoints.\n\nSupports:\n - Complex filters using LogicalOperator (AND, OR, NOT)\n - Shorthand filter syntax: {\"metadata.campaign\": \"summer_2024\"}\n - Full-text search across filename and metadata\n - Multi-field sorting\n - Pagination with limit/offset\n\nExamples:\n - List all pending uploads in a bucket\n - Find uploads by metadata campaign\n - Search for uploads by filename pattern\n - Sort by file size or creation date","examples":[{"description":"List all pending uploads","filters":{"status":"PENDING"},"limit":20,"offset":0,"sort":{"direction":"desc","field":"created_at"}},{"description":"Find large completed uploads","filters":{"AND":[{"field":"status","operator":"eq","value":"COMPLETED"},{"field":"file_size_bytes","operator":"gte","value":10485760}]},"limit":50,"sort":{"direction":"desc","field":"file_size_bytes"}},{"description":"Search for video uploads in summer campaign","filters":{"metadata.campaign":"summer_2024"},"limit":100,"search":"video"},{"description":"List failed uploads for debugging","filters":{"status":"FAILED"},"limit":50,"return_presigned_urls":true,"sort":{"direction":"desc","field":"created_at"}}]},"ListUploadsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/UploadResponse"},"type":"array","title":"Results","description":"List of upload records matching the query"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination metadata including total count, limit, offset, has_more"},"stats":{"$ref":"#/components/schemas/UploadListStats","description":"Aggregate statistics across all uploads in the result"}},"type":"object","required":["results","pagination","stats"],"title":"ListUploadsResponse","description":"Response model for listing uploads.","examples":[{"pagination":{"has_more":true,"limit":20,"offset":0,"total_count":42},"results":[{"bucket_id":"bkt_prod","created_at":"2024-01-15T10:30:00Z","file_size_bytes":52428800,"filename":"video1.mp4","status":"COMPLETED","upload_id":"upl_abc123"}],"stats":{"avg_file_size_bytes":12483047,"total_size_bytes":524288000,"total_uploads":42,"unique_buckets":3,"uploads_by_status":{"COMPLETED":35,"FAILED":2,"PENDING":5}}}]},"ListWebhooksRequest":{"properties":{"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type","description":"Filter by event type"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Filter by active status"}},"type":"object","title":"ListWebhooksRequest","description":"Request for listing webhooks with filters.\n\nFilters webhooks by various criteria."},"ListWebhooksResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/Webhook-Output"},"type":"array","title":"Results","description":"List of webhooks"},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination information"},"total":{"type":"integer","title":"Total","description":"Total number of webhooks"}},"type":"object","required":["results","pagination","total"],"title":"ListWebhooksResponse","description":"Response for listing webhooks with pagination.\n\nReturns a paginated list of webhook records."},"ListingStatus":{"type":"string","enum":["draft","published","archived","suspended"],"title":"ListingStatus","description":"Status of a marketplace listing."},"ListingVisibility":{"type":"string","enum":["listed","unlisted"],"title":"ListingVisibility","description":"Visibility level for a marketplace listing.\n\n- LISTED: Appears in marketplace catalog, homepage showcase, and sitemap.\n- UNLISTED: Accessible via direct link but hidden from catalog/showcase."},"LogicalOperator-Input":{"properties":{"AND":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"And","description":"Logical AND operation - all conditions must be true","example":[{"field":"name","operator":"eq","value":"John"},{"field":"age","operator":"gte","value":30}]},"OR":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"Or","description":"Logical OR operation - at least one condition must be true","example":[{"field":"status","operator":"eq","value":"active"},{"field":"role","operator":"eq","value":"admin"}]},"NOT":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"Not","description":"Logical NOT operation - all conditions must be false","example":[{"field":"department","operator":"eq","value":"HR"},{"field":"location","operator":"eq","value":"remote"}]},"case_sensitive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Case Sensitive","description":"Whether to perform case-sensitive matching","default":false,"example":true}},"additionalProperties":true,"type":"object","title":"LogicalOperator","description":"Represents a logical operation (AND, OR, NOT) on filter conditions.\n\nAllows nesting with a defined depth limit.\n\nAlso supports shorthand syntax where field names can be passed directly\nas key-value pairs for equality filtering (e.g., {\"metadata.title\": \"value\"})."},"LogicalOperator-Output":{"properties":{"AND":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"And","description":"Logical AND operation - all conditions must be true","example":[{"field":"name","operator":"eq","value":"John"},{"field":"age","operator":"gte","value":30}]},"OR":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"Or","description":"Logical OR operation - at least one condition must be true","example":[{"field":"status","operator":"eq","value":"active"},{"field":"role","operator":"eq","value":"admin"}]},"NOT":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"$ref":"#/components/schemas/FilterCondition"}]},"type":"array"},{"type":"null"}],"title":"Not","description":"Logical NOT operation - all conditions must be false","example":[{"field":"department","operator":"eq","value":"HR"},{"field":"location","operator":"eq","value":"remote"}]},"case_sensitive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Case Sensitive","description":"Whether to perform case-sensitive matching","default":false,"example":true}},"additionalProperties":true,"type":"object","title":"LogicalOperator","description":"Represents a logical operation (AND, OR, NOT) on filter conditions.\n\nAllows nesting with a defined depth limit.\n\nAlso supports shorthand syntax where field names can be passed directly\nas key-value pairs for equality filtering (e.g., {\"metadata.title\": \"value\"})."},"ManifestSchemaDiscovery":{"properties":{"manifest_version":{"type":"string","title":"Manifest Version","description":"Current manifest schema version"},"resource_types":{"items":{"type":"string"},"type":"array","title":"Resource Types","description":"List of supported resource types"},"schemas":{"additionalProperties":true,"type":"object","title":"Schemas","description":"JSON Schema for each resource type"},"dependency_graph":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Dependency Graph","description":"Resource dependencies (key depends on values)"},"examples":{"additionalProperties":{"type":"string"},"type":"object","title":"Examples","description":"YAML example for each resource type"}},"type":"object","required":["manifest_version","resource_types","schemas","dependency_graph"],"title":"ManifestSchemaDiscovery","description":"Manifest schema discovery for agent-driven configuration.","examples":[{"dependency_graph":{"bucket":["namespace"],"collection":["namespace","bucket"],"retriever":["namespace","collection"]},"examples":{"namespace":"namespaces:\n - name: my_ns\n feature_extractors:\n - name: multimodal_extractor"},"manifest_version":"1.0","resource_types":["namespace","bucket","collection","retriever"],"schemas":{"namespace":{"properties":{},"type":"object"}}}]},"MarkAsReadRequest":{"properties":{"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID to mark all as read for"}},"type":"object","title":"MarkAsReadRequest","description":"Request model for marking notifications as read."},"MarkdownContent":{"properties":{"title":{"type":"string","maxLength":200,"minLength":1,"title":"Title","description":"Title for the markdown content section","examples":["How it Works","Getting Started","About This Search","Search Tips"]},"content":{"type":"string","maxLength":50000,"minLength":1,"title":"Content","description":"Markdown-formatted content. Supports standard markdown syntax including headers, lists, links, images, code blocks, and emphasis. Limited to 50KB to prevent database issues.","examples":["# Welcome\n\nThis search uses **AI** to understand your queries.","## Features\n\n- Semantic search\n- Multi-modal\n- Fast results","### Tips\n\n1. Use specific terms\n2. Try multiple queries\n\n[Learn more](https://docs.example.com)"]}},"type":"object","required":["title","content"],"title":"MarkdownContent","description":"Reusable markdown content model with title and content.\n\nThis model provides a structured way to include rich markdown content\nanywhere in the published retriever configuration. Includes safety\nconstraints to prevent database issues."},"MarketplaceListing":{"properties":{"listing_id":{"type":"string","title":"Listing Id","description":"Unique identifier for the listing"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization that owns this listing (provider)"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace containing the retriever"},"retriever_id":{"type":"string","title":"Retriever Id","description":"Retriever being offered in the marketplace"},"title":{"type":"string","title":"Title","description":"Public display title","examples":["Brand Safety Classification API","Video Search Engine"]},"description":{"type":"string","title":"Description","description":"Public description of what this listing provides"},"public_name":{"type":"string","maxLength":50,"minLength":3,"title":"Public Name","description":"Public URL-safe slug for the listing (e.g., 'video-search'). Used in public URL: mxp.co/m/{public_name}. Must be globally unique.","examples":["brand-safety-api","video-search","product-catalog"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Category for browsing (e.g., 'Content Moderation', 'Search')"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for discovery"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"URL to listing logo/icon"},"icon_base64":{"anyOf":[{"type":"string","maxLength":300000},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon (data URI format). Max size: ~200KB encoded. Use for small icons.","examples":["data:image/png;base64,iVBORw0KGgoAAAANS..."]},"available_tiers":{"items":{"$ref":"#/components/schemas/SubscriptionTierConfig"},"type":"array","title":"Available Tiers","description":"Available subscription tiers (must include at least one tier, typically FREE for public listings)"},"display_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Display Config","description":"JSON-based UI configuration for the public interface. Follows a component-based schema (inspired by json-render): { 'components': [...], 'theme': {...}, 'layout': {...} }. If not provided, a default UI is generated from retriever input_schema.","examples":[{"components":[{"props":{"field":"video_url","label":"Enter video URL"},"type":"SearchInput"},{"props":{"fields":["title","description","score"],"layout":"grid"},"type":"ResultCard"}],"theme":{"fontFamily":"Inter, sans-serif","primaryColor":"#007AFF"}}]},"password_secret_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password Secret Name","description":"Optional organization secret name containing password for access protection. If set, users must provide password to subscribe (even for free tier).","examples":["marketplace_password","demo_access_password"]},"status":{"$ref":"#/components/schemas/ListingStatus","description":"Publication status","default":"draft"},"visibility":{"$ref":"#/components/schemas/ListingVisibility","description":"Visibility level. 'listed' = shown in marketplace catalog & homepage showcase. 'unlisted' = accessible via direct link only (not in catalog).","default":"unlisted"},"is_active":{"type":"boolean","title":"Is Active","description":"DEPRECATED: Use 'status' field instead. Computed from status (True if PUBLISHED, False otherwise).","default":true,"deprecated":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the listing was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the listing was last updated"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At","description":"When the listing was first published"},"total_subscribers":{"type":"integer","title":"Total Subscribers","description":"Total number of active subscribers","default":0},"total_queries":{"type":"integer","title":"Total Queries","description":"Total queries executed across all subscribers","default":0}},"type":"object","required":["internal_id","namespace_id","retriever_id","title","description","public_name","available_tiers"],"title":"MarketplaceListing","description":"A marketplace listing for a retriever.\n\nThis is the unified model for all public and marketplace retrievers.\nReplaces the PublishedRetriever system with a simpler, more flexible approach.\n\nFree tier = public retriever (anyone can subscribe for free)\nPaid tiers = monetized marketplace offering"},"MeanShiftParams":{"properties":{"bandwidth":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Bandwidth","description":"Bandwidth used in the RBF kernel. If None, estimated using sklearn.cluster.estimate_bandwidth"},"seeds":{"anyOf":[{"items":{"items":{"type":"number"},"type":"array"},"type":"array"},{"type":"null"}],"title":"Seeds","description":"Seeds used to initialize kernels. If None, all points are used as seeds"},"bin_seeding":{"type":"boolean","title":"Bin Seeding","description":"If true, initial kernel locations are discretized into a grid to speed up algorithm","default":false},"min_bin_freq":{"type":"integer","minimum":1.0,"title":"Min Bin Freq","description":"Minimum number of seeds within a bin for the bin to be considered","default":1},"cluster_all":{"type":"boolean","title":"Cluster All","description":"If true, all points are clustered, even orphans. If false, orphans are given label -1","default":true},"n_jobs":{"type":"integer","title":"N Jobs","description":"Number of parallel jobs to run (-1 means using all processors)","default":1},"max_iter":{"type":"integer","minimum":1.0,"title":"Max Iter","description":"Maximum number of iterations per seed point before the algorithm stops","default":300}},"type":"object","title":"MeanShiftParams","description":"Parameters for Mean Shift clustering algorithm."},"MessageHistoryItem":{"properties":{"message_id":{"type":"string","title":"Message Id","description":"Message identifier"},"role":{"type":"string","title":"Role","description":"Message role"},"content":{"type":"string","title":"Content","description":"Message content"},"content_type":{"type":"string","title":"Content Type","description":"Content type"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name","description":"Tool name (if tool message)"},"tool_inputs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Inputs","description":"Tool inputs (if tool call)"},"tool_outputs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Outputs","description":"Tool outputs (if tool result)"},"tool_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Status","description":"Tool status (if tool message)"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Message timestamp"}},"type":"object","required":["message_id","role","content","content_type","timestamp"],"title":"MessageHistoryItem","description":"Single message in conversation history.\n\nAttributes:\n message_id: Message identifier\n role: Message role (user, assistant, tool)\n content: Message text content\n content_type: Content type (text, tool_call, tool_result)\n tool_name: Tool name (if tool message)\n tool_inputs: Tool inputs (if tool call)\n tool_outputs: Tool outputs (if tool result)\n tool_status: Tool execution status (if tool message)\n timestamp: Message timestamp"},"MigrationConfig":{"properties":{"migration_type":{"$ref":"#/components/schemas/MigrationType","description":"Type of migration to perform"},"source_namespace_id":{"type":"string","title":"Source Namespace Id","description":"Source namespace ID"},"target_namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Namespace Id","description":"Target namespace ID (auto-generated if not provided)"},"target_namespace_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Namespace Name","description":"Name for target namespace"},"feature_extractors":{"anyOf":[{"items":{"$ref":"#/components/schemas/shared__namespaces__migrations__models__FeatureExtractorConfig"},"type":"array"},{"type":"null"}],"title":"Feature Extractors","description":"New extractors to use (RE_EXTRACT only)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ResourceFilter"},{"type":"null"}],"description":"Resource selection filters"},"batch_options":{"anyOf":[{"$ref":"#/components/schemas/BatchOptions"},{"type":"null"}],"description":"Batch processing options"},"taxonomy_options":{"anyOf":[{"$ref":"#/components/schemas/TaxonomyOptions"},{"type":"null"}],"description":"Taxonomy migration options"},"cluster_options":{"anyOf":[{"$ref":"#/components/schemas/ClusterOptions"},{"type":"null"}],"description":"Cluster migration options"},"retriever_options":{"anyOf":[{"$ref":"#/components/schemas/RetrieverOptions"},{"type":"null"}],"description":"Retriever migration options"},"preserve_resource_ids":{"type":"boolean","title":"Preserve Resource Ids","description":"Preserve original resource IDs in target","default":false},"dry_run":{"type":"boolean","title":"Dry Run","description":"Validate only, don't execute","default":false},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"Webhook URL for status notifications"}},"type":"object","required":["migration_type","source_namespace_id"],"title":"MigrationConfig","description":"Configuration for a namespace migration."},"MigrationProgress":{"properties":{"overall_status":{"$ref":"#/components/schemas/MigrationStatus","description":"Overall migration status"},"overall_progress_percent":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Overall Progress Percent","description":"Overall progress %","default":0.0},"current_stage":{"anyOf":[{"$ref":"#/components/schemas/MigrationStage"},{"type":"null"}],"description":"Currently executing stage"},"stages":{"items":{"$ref":"#/components/schemas/StageProgress"},"type":"array","title":"Stages","description":"Progress for each stage"},"resources":{"items":{"$ref":"#/components/schemas/ResourceProgress"},"type":"array","title":"Resources","description":"Progress for each resource"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"Migration start time"},"estimated_completion":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Estimated Completion","description":"Estimated completion time"}},"type":"object","required":["overall_status"],"title":"MigrationProgress","description":"Overall progress tracking for a migration."},"MigrationStage":{"type":"string","enum":["namespace_setup","batch_creation","batch_processing","cluster_execution","taxonomy_enrichment","benchmark_evaluation","finalization"],"title":"MigrationStage","description":"Stages of migration execution."},"MigrationStatus":{"type":"string","enum":["draft","validating","pending","in_progress","completed","failed","cancelled"],"title":"MigrationStatus","description":"Migration execution status."},"MigrationType":{"type":"string","enum":["re_extract","copy","extend"],"title":"MigrationType","description":"Types of namespace migrations."},"ModelDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"model_id":{"type":"string","title":"Model Id"},"message":{"type":"string","title":"Message"}},"type":"object","required":["model_id","message"],"title":"ModelDeleteResponse","description":"Response model for model deletion."},"ModelDeployResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether deployment succeeded"},"model_id":{"type":"string","title":"Model Id","description":"Model identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"deployment_status":{"type":"string","title":"Deployment Status","description":"Deployment status (deployed, failed)"},"cached":{"type":"boolean","title":"Cached","description":"Whether model is cached in object store","default":false},"message":{"type":"string","title":"Message","description":"Status message"}},"type":"object","required":["success","model_id","namespace_id","deployment_status","message"],"title":"ModelDeployResponse","description":"Response model for model deployment.\n\nDeploying a model pre-loads the weights into the Ray object store,\nmaking them available for zero-copy access by plugins."},"ModelDeploymentInfo":{"properties":{"ray_cluster_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Cluster Url","description":"Ray cluster URL where model is deployed"},"ray_deployment_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Deployment Name","description":"Ray deployment name"},"endpoint":{"type":"string","title":"Endpoint","description":"HTTP endpoint for model inference"},"base_image":{"type":"string","title":"Base Image","description":"Docker image used for deployment"},"deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployed At","description":"When the model was deployed"}},"type":"object","required":["endpoint","base_image"],"title":"ModelDeploymentInfo","description":"Deployment information for a model."},"ModelDetailResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"model":{"$ref":"#/components/schemas/CustomModelDocument"}},"type":"object","required":["model"],"title":"ModelDetailResponse","description":"Response model for model details."},"ModelListItem":{"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"},"framework":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Framework"},"task_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Type"},"deployed":{"type":"boolean","title":"Deployed"},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["model_id","name","version","model_format","deployed","created_at","updated_at"],"title":"ModelListItem","description":"Model item in list response."},"ModelListResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"models":{"items":{"$ref":"#/components/schemas/ModelListItem"},"type":"array","title":"Models"},"total":{"type":"integer","title":"Total"},"namespace_id":{"type":"string","title":"Namespace Id"}},"type":"object","required":["models","total","namespace_id"],"title":"ModelListResponse","description":"Response model for listing models."},"ModelPresignedURLResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id","description":"Upload ID to use when confirming"},"presigned_url":{"type":"string","title":"Presigned Url","description":"S3 presigned URL for PUT upload"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key where file will be stored"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the presigned URL expires"},"organization_id":{"type":"string","title":"Organization Id","description":"Organization ID"},"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"}},"type":"object","required":["upload_id","presigned_url","s3_key","expires_at","organization_id","name","version","model_format"],"title":"ModelPresignedURLResponse","description":"Response containing presigned URL for model upload.\n\nAfter receiving this response:\n1. PUT the model archive to `presigned_url` with Content-Type: application/gzip\n2. Call POST /models/uploads/{upload_id}/confirm to finalize"},"ModelResourceRequirements":{"properties":{"num_cpus":{"type":"number","maximum":64.0,"minimum":0.1,"title":"Num Cpus","description":"Number of CPUs","default":1.0},"num_gpus":{"type":"integer","maximum":8.0,"minimum":0.0,"title":"Num Gpus","description":"Number of GPUs","default":0},"memory":{"type":"integer","title":"Memory","description":"Memory in bytes (default 4GB)","default":4294967296}},"type":"object","title":"ModelResourceRequirements","description":"Resource requirements for model deployment."},"ModelUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether upload succeeded"},"model_id":{"type":"string","title":"Model Id","description":"Unique model identifier"},"deployment_status":{"type":"string","enum":["deployed","pending","failed","not_deployed"],"title":"Deployment Status","description":"Deployment status"},"endpoint":{"type":"string","title":"Endpoint","description":"Model inference endpoint"},"model_archive_url":{"type":"string","title":"Model Archive Url","description":"S3 URL where archive is stored"}},"type":"object","required":["success","model_id","deployment_status","endpoint","model_archive_url"],"title":"ModelUploadResponse","description":"Response model for model upload."},"MostQueriedFieldsResponse":{"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"},"fields":{"items":{"$ref":"#/components/schemas/FieldQueryMetrics"},"type":"array","title":"Fields","description":"Most queried fields"},"total_fields":{"type":"integer","title":"Total Fields","description":"Total unique fields found"}},"type":"object","required":["namespace_id","time_range_days","fields","total_fields"],"title":"MostQueriedFieldsResponse","description":"Response for most queried fields endpoint."},"MultiDenseVector":{"properties":{},"additionalProperties":true,"type":"object","title":"MultiDenseVector","description":"Multi-dimensional dense vector representation with flexible key naming.\n\nAccepts a single key-value pair where the key can be any string\nand the value must be a list of lists of floats.\nUseful for late interaction models and other multi-dimensional embeddings.\n\nExample:\n```json\n{\n \"embeddings\": [\n [0.1, 0.2, 0.3],\n [0.4, 0.5, 0.6],\n [0.7, 0.8, 0.9]\n ]\n}\n```\nor\n```json\n{\n \"multi_vectors\": [\n [0.1, 0.2, 0.3],\n [0.4, 0.5, 0.6],\n [0.7, 0.8, 0.9]\n ]\n}\n```"},"MultiVectorIndex":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"REQUIRED. Fully-qualified name for the multi-vector index. Format: {extractor}_{version}_{output} (e.g., 'hybrid_extractor_v1_multi'). Must be unique across namespace.","examples":["hybrid_extractor_v1_multi","ensemble_v1_combined"]},"description":{"type":"string","minLength":10,"title":"Description","description":"REQUIRED. Human-readable description of the multi-vector index. Explain what vector types are included and their purposes. Describe use cases for this multi-vector configuration.","examples":["Hybrid dense + sparse embeddings for enhanced retrieval","Multi-model ensemble with BERT + RoBERTa embeddings"]},"vectors":{"additionalProperties":{"$ref":"#/components/schemas/VectorIndex"},"type":"object","title":"Vectors","description":"REQUIRED. Dictionary mapping vector output names to their VectorIndex configurations. Each key is a unique identifier for that vector type within this multi-index. Each value is a complete VectorIndex with its own dimensions, type, and inference service. Example keys: 'dense', 'sparse', 'primary', 'secondary'.","examples":[{"dense":{"dimensions":1024,"inference_name":"e5_large","name":"hybrid_v1_dense","type":"dense"},"sparse":{"inference_name":"splade","name":"hybrid_v1_sparse","type":"sparse"}}]}},"type":"object","required":["name","description","vectors"],"title":"MultiVectorIndex","description":"Configuration for multi-vector indexes.\n\nAllows a single extractor to produce multiple named vector outputs in one index.\nUseful for hybrid search combining different embedding types or multiple models.\n\nUse Cases:\n - Hybrid dense + sparse embeddings in one index\n - Multiple models for ensemble retrieval\n - Different granularities (sentence + paragraph embeddings)\n\nRequirements:\n - name: REQUIRED - Full qualified name for the multi-vector index\n - description: REQUIRED - Explain what vector combinations are included\n - vectors: REQUIRED - Dictionary mapping output names to VectorIndex configs\n\nNote: Currently less common than single VectorIndex. Most extractors use\nseparate VectorIndexDefinitions for each output instead.","examples":[{"description":"Combined dense and sparse embeddings for hybrid search. Dense provides semantic understanding, sparse adds keyword precision.","name":"hybrid_extractor_v1_multi","vectors":{"dense":{"datatype":"float32","description":"Dense semantic embedding","dimensions":1024,"distance":"cosine","inference_name":"multilingual_e5_large_instruct_v1","name":"hybrid_v1_dense","type":"dense"},"sparse":{"datatype":"float32","description":"Sparse keyword embedding","distance":"dot","inference_name":"splade_plus_plus_v1","name":"hybrid_v1_sparse","type":"sparse"}}}]},"MultimodalExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"multimodal_extractor","title":"Extractor Type","description":"Discriminator field for parameter type identification. Must be 'multimodal_extractor'.","default":"multimodal_extractor"},"split_method":{"$ref":"#/components/schemas/SplitMethod","description":"The PRIMARY control for video splitting strategy. This determines which splitting method is used.","default":"time"},"description_prompt":{"type":"string","title":"Description Prompt","description":"The prompt to use for description generation.","default":"Describe the video segment in detail."},"time_split_interval":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Time Split Interval","description":"Interval in seconds for 'time' splitting. Used when split_method='time'.","default":10},"silence_db_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Silence Db Threshold","description":"The decibel level below which audio is considered silent. Used when split_method='silence'. Recommended value: -40 (auto-applied if not specified). Lower values (e.g., -50) detect more silence, higher values (e.g., -30) detect less."},"scene_detection_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Scene Detection Threshold","description":"The threshold for scene detection (0.0-1.0). Used when split_method='scene'. Recommended value: 0.5 (auto-applied if not specified). Lower values (e.g., 0.3) detect more scenes, higher values (e.g., 0.7) detect fewer scenes."},"run_transcription":{"type":"boolean","title":"Run Transcription","description":"Whether to run transcription on video segments.","default":false},"transcription_language":{"type":"string","title":"Transcription Language","description":"The language of the transcription. Used when run_transcription is True.","default":"en"},"run_video_description":{"type":"boolean","title":"Run Video Description","description":"Whether to generate descriptions for video segments. OPTIMIZED: Defaults to False as descriptions add 1-2 minutes. Enable only when needed.","default":false},"run_transcription_embedding":{"type":"boolean","title":"Run Transcription Embedding","description":"Whether to generate embeddings for transcriptions. Useful for semantic search over spoken content.","default":false},"run_multimodal_embedding":{"type":"boolean","title":"Run Multimodal Embedding","description":"Whether to generate multimodal embeddings for all content types (video/image/gif/text). Uses Google Vertex AI to create unified 1408D embeddings in a shared semantic space. Useful for cross-modal semantic search across all media types.","default":true},"run_ocr":{"type":"boolean","title":"Run Ocr","description":"Whether to run OCR to extract text from video frames. OPTIMIZED: Defaults to False as OCR adds significant processing time. Enable only when text extraction from video is required.","default":false},"sensitivity":{"type":"string","title":"Sensitivity","description":"The sensitivity of the scene detection.","default":"low"},"enable_thumbnails":{"type":"boolean","title":"Enable Thumbnails","description":"Whether to generate thumbnail images for video segments and images. Thumbnails provide visual previews for navigation and UI display. For videos: Extracts a frame from each segment. For images: Creates an optimized thumbnail version. ","default":true},"use_cdn":{"type":"boolean","title":"Use Cdn","description":"Whether to use CloudFront CDN for thumbnail delivery. When True: Uploads to public bucket and returns CloudFront URLs. When False (default): Uploads to private bucket with presigned S3 URLs. Benefits of CDN: faster global delivery, permanent URLs, reduced bandwidth costs. Requires CLOUDFRONT_PUBLIC_DOMAIN to be configured in settings. Only applies when enable_thumbnails=True.","default":false},"generation_config":{"$ref":"#/components/schemas/GenerationConfig"},"response_shape":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Shape","description":"OPTIONAL. Define custom structured output using Gemini's JSON mode. NOT REQUIRED - by default, descriptions are stored as plain text. When provided, Gemini will extract structured data matching this schema. \n\nTwo modes supported:\n1. Natural language prompt (string): Describe desired output in plain English\n - Gemini automatically infers JSON schema from your description\n - Example: 'Extract product names, colors, and aesthetic labels'\n\n2. Explicit JSON schema (dict): Provide complete JSON schema for output structure\n - Full control over output structure, types, and constraints\n - Use response_mime_type='application/json' in generation_config\n - Example: {'type': 'object', 'properties': {'products': {'type': 'array', ...}}}\n\n\nUse when:\n - Need to extract structured product/entity information from videos\n - Want consistent, parseable output format (not free-form text)\n - Require specific fields like visibility_percentage, product categories, etc.\n - Building e-commerce, fashion, or product discovery applications\n\n\nOutput fields are automatically added to collection schema and stored in document metadata.\nNote: When using response_shape, set description_prompt to describe the extraction task.\n","examples":["Extract product names, colors, materials, and aesthetic style labels from this fashion segment",{"properties":{"products":{"items":{"properties":{"name":{"type":"string"},"category":{"type":"string"},"visibility_percentage":{"maximum":100,"minimum":0,"type":"integer"}},"type":"object"},"type":"array"},"aesthetic":{"type":"string"}},"type":"object"},null]}},"type":"object","title":"MultimodalExtractorParams","description":"Parameters for the multimodal extractor.\n\nThe multimodal extractor processes video, audio, image, text, and GIF content in a unified embedding space.\nVideos/GIFs/Audio are decomposed into segments with transcription, visual analysis (video only), OCR, and embeddings.\nImages and text are embedded directly without decomposition.\n\n**When to Use**:\n - Video content libraries requiring searchable segments\n - Audio content (podcasts, lectures, music) requiring transcription and search\n - Media platforms with search across spoken and visual content\n - Educational content with lecture videos and demonstrations\n - Surveillance/security footage requiring event detection\n - Social media platforms with user-generated video content\n - Broadcasting/streaming services with large video catalogs\n - Training video repositories with instructional content\n - Marketing/advertising analytics for video campaigns\n\n**When NOT to Use**:\n - Static image collections ā†’ Use image_extractor instead\n - Very short videos (<5 seconds) ā†’ Overhead not worth it\n - Real-time live streams ā†’ Use specialized streaming extractors\n - Extremely high-resolution videos (8K+) ā†’ Consider downsampling first\n\n**Decomposition Methods**:\n\n | Method | Use Case | Accuracy | Segments/Min | Best For |\n |--------|----------|----------|--------------|----------|\n | **TIME** | Fixed intervals | N/A | 60/interval_sec | General purpose, audio/video chunking |\n | **SCENE** | Visual changes | 85-90% | Variable (2-20) | Movies, dynamic content (video only) |\n | **SILENCE** | Audio pauses | 80-85% | Variable (5-30) | Lectures, presentations, audio/video |\n\n**Feature Extraction Options**:\n - Transcription: Speech-to-text using Whisper (95%+ accuracy)\n - Multimodal Embeddings: Unified embeddings from Vertex AI (1408D) for video/image/gif/text\n - Transcription Embeddings: Text embeddings from E5-Large (1024D)\n - OCR: Text extraction from video frames using Gemini Vision\n - Descriptions: AI-generated segment summaries using Gemini\n - Thumbnails: Visual preview images for each segment\n\n**Performance Characteristics**:\n - Processing Speed: 0.5-2x realtime (depends on features enabled)\n - Example: 10min video ā†’ 5-20 minutes processing time\n - Transcription: ~200ms per second of audio\n - Visual Embedding: ~50ms per segment\n - OCR: ~300ms per segment\n - Description: ~2s per segment (if enabled)\n\nRequirements:\n - video URL: REQUIRED (accessible video file)\n - All feature parameters: OPTIONAL (defaults provided)","examples":[{"description":"Standard video processing with 10-second intervals (default)","enable_thumbnails":true,"extractor_type":"multimodal_extractor","run_multimodal_embedding":true,"split_method":"time","time_split_interval":10,"use_case":"General-purpose video indexing for search and discovery"},{"description":"Educational content with transcription + embeddings","extractor_type":"multimodal_extractor","run_multimodal_embedding":true,"run_transcription":true,"run_transcription_embedding":true,"split_method":"time","time_split_interval":10,"transcription_language":"en","use_case":"Lecture videos and online courses requiring searchable spoken content"}]},"NamedDenseVectors":{"additionalProperties":{"items":{"type":"number"},"type":"array"},"type":"object","title":"NamedDenseVectors","description":"Root model mapping vector names ā†’ dense float lists.\n\nAccepts JSON like:\n```json\n{\n \"vector_a\": [0.1, 0.2, 0.3],\n \"vector_b\": [0.4, 0.5, 0.6]\n}\n```"},"NamespaceInfrastructure":{"properties":{"ray_cluster_id":{"anyOf":[{"type":"string","pattern":"^ray_[a-zA-Z0-9_]{3,64}$"},{"type":"null"}],"title":"Ray Cluster Id","description":"Dedicated Ray cluster identifier for this namespace.","examples":["ray_shared","ray_prod_gpu_cluster",null]},"ray_head_node_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Head Node Url","description":"Ray head node address for job submission (ray://host:port).","examples":["ray://shared-cluster:10001","ray://gpu-cluster-head:10001"]},"ray_dashboard_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Dashboard Url","description":"Ray dashboard URL for monitoring (http://host:8265).","examples":["http://ray-dashboard-prod:8265"]},"qdrant_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qdrant Url","description":"Dedicated Qdrant instance URL for this namespace. When set, this namespace uses its own Qdrant instance instead of organization or shared infrastructure. Format: http://hostname:port or https://hostname:port. REQUIRED when compute_tier is DEDICATED_CPU or DEDICATED_GPU. NOT REQUIRED for SHARED tier (inherits from organization or uses shared).","examples":["http://qdrant-ns-prod:6333","https://qdrant-namespace.example.com:6333"]},"qdrant_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qdrant Api Key","description":"API key for dedicated Qdrant instance. REQUIRED when qdrant_url is set. NOT REQUIRED for shared tier.","examples":["qdrant_key_namespace_123"]},"qdrant_collection":{"type":"string","maxLength":128,"minLength":3,"title":"Qdrant Collection","description":"Qdrant collection backing this namespace's vector data.","examples":["ns_production","ns_ml_inference"]},"s3_vector_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Vector Bucket","description":"S3 Vectors bucket name for vector tiering. When set, vectors are durably stored in S3."},"compute_tier":{"$ref":"#/components/schemas/ComputeTier","description":"Compute tier controlling isolation and performance characteristics.","default":"shared","examples":["shared","dedicated_cpu","dedicated_gpu"]},"max_concurrent_jobs":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Max Concurrent Jobs","description":"Maximum concurrent Ray jobs allowed for the namespace.","default":10,"examples":[10,50,20]},"autoscaling_enabled":{"type":"boolean","title":"Autoscaling Enabled","description":"Toggle autoscaling for dedicated clusters (ignored for shared tier).","default":true},"min_workers":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Min Workers","description":"Lower bound for Ray workers when autoscaling is enabled.","default":1},"max_workers":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Max Workers","description":"Upper bound for Ray workers when autoscaling is enabled.","default":10},"gpu_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gpu Type","description":"GPU type for dedicated GPU clusters (e.g. A100, T4).","examples":["A100","T4",null]},"gpus_per_worker":{"type":"integer","maximum":8.0,"minimum":0.0,"title":"Gpus Per Worker","description":"Number of GPUs allocated to each Ray worker when using GPUs.","default":1},"s3_plugin_bucket":{"type":"string","title":"S3 Plugin Bucket","description":"S3 bucket for storing custom plugins and model weights.","default":"mixpeek-plugins"},"s3_plugin_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"S3 Plugin Prefix","description":"S3 prefix for namespace-scoped plugin storage. Format: {namespace_id}/ when custom plugins are enabled.","examples":["ns_abc123/"]},"max_custom_plugins":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Max Custom Plugins","description":"Maximum number of custom plugins allowed for this namespace. 0 = custom plugins disabled (shared tier). Set to >0 for dedicated tiers to enable custom plugins.","default":0},"max_custom_models":{"type":"integer","maximum":50.0,"minimum":0.0,"title":"Max Custom Models","description":"Maximum number of custom model weights allowed for this namespace. 0 = custom models disabled (shared tier). Set to >0 for dedicated tiers to enable custom model uploads.","default":0}},"type":"object","required":["qdrant_collection"],"title":"NamespaceInfrastructure","description":"Infrastructure configuration associated with a namespace.\n\nDefines infrastructure resources for a specific namespace. This configuration\ncan override organization-level defaults, enabling flexible deployment patterns\nwhere different namespaces use different infrastructure.\n\nResolution Priority:\n When a namespace has infrastructure configured with DEDICATED tier, it takes\n precedence over organization-level infrastructure. This allows:\n - ENTERPRISE org with SHARED namespace (cost savings for dev/test)\n - ENTERPRISE org with dedicated GPU namespace (ML workloads)\n - Mixed infrastructure within a single organization\n\nTier Behaviors:\n SHARED:\n - Namespace uses organization infrastructure (if configured)\n - Falls back to Mixpeek's shared infrastructure\n - All infrastructure URLs should be None\n - Lowest cost, multi-tenant\n\n DEDICATED_CPU:\n - Namespace uses its own dedicated CPU infrastructure\n - Requires qdrant_url, qdrant_api_key, ray_head_node_url\n - Single-tenant CPU compute\n - Medium cost\n\n DEDICATED_GPU:\n - Namespace uses its own dedicated GPU infrastructure\n - Requires qdrant_url, qdrant_api_key, ray_head_node_url\n - Requires gpu_type and gpus_per_worker configuration\n - Single-tenant GPU compute\n - Highest cost\n\nUse Cases:\n - Development namespace: Set compute_tier=SHARED to use organization's infrastructure\n - Production namespace: Inherit organization's DEDICATED infrastructure (don't override)\n - ML namespace: Override with DEDICATED_GPU and GPU configuration\n - Cost optimization: Override ENTERPRISE org to SHARED for dev/test namespaces\n\nExamples:\n Inherits organization infrastructure (no override):\n NamespaceInfrastructure(\n qdrant_collection=\"ns_production\",\n compute_tier=ComputeTier.SHARED # Uses org or shared infrastructure\n )\n\n Override to dedicated CPU:\n NamespaceInfrastructure(\n qdrant_url=\"http://qdrant-ns-prod:6333\",\n qdrant_api_key=\"qdrant_key_ns_123\",\n qdrant_collection=\"ns_production\",\n ray_head_node_url=\"ray://ray-ns-prod:10001\",\n ray_dashboard_url=\"http://ray-ns-dashboard:8265\",\n compute_tier=ComputeTier.DEDICATED_CPU,\n max_concurrent_jobs=50\n )\n\n Override to dedicated GPU:\n NamespaceInfrastructure(\n qdrant_url=\"http://qdrant-gpu:6333\",\n qdrant_api_key=\"qdrant_key_gpu\",\n qdrant_collection=\"ns_ml\",\n ray_head_node_url=\"ray://ray-gpu:10001\",\n compute_tier=ComputeTier.DEDICATED_GPU,\n gpu_type=\"A100\",\n gpus_per_worker=2\n )","examples":[{"autoscaling_enabled":false,"compute_tier":"shared","description":"Shared development namespace","max_concurrent_jobs":10,"qdrant_collection":"ns_dev","ray_head_node_url":"ray://shared-cluster:10001"},{"autoscaling_enabled":true,"compute_tier":"dedicated_cpu","description":"Dedicated production CPU cluster","max_concurrent_jobs":50,"max_workers":20,"min_workers":3,"qdrant_collection":"ns_production","ray_cluster_id":"ray_prod_cluster","ray_dashboard_url":"http://prod-dashboard:8265","ray_head_node_url":"ray://prod-head:10001"}]},"NamespaceListStats":{"properties":{"total_feature_extractors":{"type":"integer","title":"Total Feature Extractors","description":"Total number of feature extractors across all namespaces","default":0},"total_payload_indexes":{"type":"integer","title":"Total Payload Indexes","description":"Total number of payload indexes across all namespaces","default":0},"total_documents":{"type":"integer","title":"Total Documents","description":"Total number of documents across all namespaces","default":0},"total_buckets":{"type":"integer","title":"Total Buckets","description":"Total number of buckets across all namespaces","default":0},"total_collections":{"type":"integer","title":"Total Collections","description":"Total number of collections across all namespaces","default":0},"total_objects":{"type":"integer","title":"Total Objects","description":"Total number of objects across all namespaces","default":0},"avg_feature_extractors_per_namespace":{"type":"number","title":"Avg Feature Extractors Per Namespace","description":"Average number of feature extractors per namespace","default":0.0},"avg_payload_indexes_per_namespace":{"type":"number","title":"Avg Payload Indexes Per Namespace","description":"Average number of payload indexes per namespace","default":0.0},"avg_documents_per_namespace":{"type":"number","title":"Avg Documents Per Namespace","description":"Average number of documents per namespace","default":0.0},"avg_buckets_per_namespace":{"type":"number","title":"Avg Buckets Per Namespace","description":"Average number of buckets per namespace","default":0.0},"avg_collections_per_namespace":{"type":"number","title":"Avg Collections Per Namespace","description":"Average number of collections per namespace","default":0.0},"avg_objects_per_namespace":{"type":"number","title":"Avg Objects Per Namespace","description":"Average number of objects per namespace","default":0.0}},"type":"object","title":"NamespaceListStats","description":"Aggregate statistics for a list of namespaces."},"NamespaceModel":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"Unique identifier for the namespace"},"namespace_name":{"type":"string","title":"Namespace Name","description":"Name of the namespace","example":"spotify_playlists_dev"},"namespace_type":{"$ref":"#/components/schemas/NamespaceType","description":"Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets that can be subscribed to.","default":"standard"},"infrastructure":{"anyOf":[{"$ref":"#/components/schemas/NamespaceInfrastructure"},{"type":"null"}],"description":"Infrastructure configuration for the namespace (Ray, Qdrant)."},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Id","description":"Infrastructure cluster ID for this namespace (Enterprise only). When set, this namespace uses dedicated Anyscale/Ray + Qdrant cluster. If None, uses shared infrastructure or organization-level infrastructure. Format: iclstr_xxx","examples":["iclstr_abc123xyz",null]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the namespace"},"feature_extractors":{"items":{"$ref":"#/components/schemas/BaseFeatureExtractorModel-Output"},"type":"array","title":"Feature Extractors","description":"List of feature extractors configured for this namespace"},"payload_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayloadIndexConfig-Output"},"type":"array"},{"type":"null"}],"title":"Payload Indexes","description":"Custom payload indexes configured for this namespace"},"document_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Document Count","description":"Total number of documents in this namespace (from Qdrant collection)"},"bucket_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bucket Count","description":"Total number of buckets in this namespace"},"collection_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Collection Count","description":"Total number of collections in this namespace"},"object_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Object Count","description":"Total number of objects across all buckets in this namespace"},"auto_create_indexes":{"type":"boolean","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.","default":false},"vector_inference_map":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Vector Inference Map","description":"Mapping of vector index names to inference service names. Built at namespace creation based on extractor configurations. Used by feature search to determine correct inference service for queries. Example: {'image_extractor_v1_embedding': 'google_siglip_base_v1'}"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the namespace was created"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When the namespace was last updated"}},"type":"object","required":["namespace_name"],"title":"NamespaceModel","description":"Namespace model."},"NamespaceOperation":{"type":"string","enum":["read_data","write_data","delete_data","execute_retriever","create_retriever","delete_retriever","execute_job","cancel_job","create_cluster","delete_cluster","modify_cluster","modify_infrastructure","manage_permissions"],"title":"NamespaceOperation","description":"Granular operations that can be scoped inside a namespace.\n\nThese operations are used to define fine-grained permissions for API keys and users\nwithin specific namespaces. Operations can be granted individually or in combination\nto implement least-privilege access control.\n\nData operations:\n - READ_DATA: View and search documents, retrieve objects from buckets\n - WRITE_DATA: Create and update documents, upload objects to buckets\n - DELETE_DATA: Remove documents and objects permanently\n\nRetrieval operations:\n - EXECUTE_RETRIEVER: Run search queries using configured retrievers\n - CREATE_RETRIEVER: Define new retrieval pipelines with custom stages\n - DELETE_RETRIEVER: Remove retrieval pipeline configurations\n\nJob execution:\n - EXECUTE_JOB: Trigger ingestion pipelines and batch processing jobs\n - CANCEL_JOB: Abort running jobs before completion\n\nCluster management (Ray infrastructure):\n - CREATE_CLUSTER: Provision new Ray compute clusters\n - DELETE_CLUSTER: Tear down existing compute clusters\n - MODIFY_CLUSTER: Scale or reconfigure running clusters\n\nInfrastructure configuration:\n - MODIFY_INFRASTRUCTURE: Change namespace settings, storage connections\n - MANAGE_PERMISSIONS: Grant and revoke user access within the namespace\n\nExamples:\n - Read-only access: [READ_DATA, EXECUTE_RETRIEVER]\n - Data engineer access: [READ_DATA, WRITE_DATA, EXECUTE_JOB]\n - Full namespace admin: All operations granted"},"NamespaceSummaryResponse":{"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"},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Summary statistics (total_fields_analyzed, high_priority_indexes, etc.)"},"recommendations":{"items":{"$ref":"#/components/schemas/IndexRecommendation"},"type":"array","title":"Recommendations","description":"Top index recommendations"},"most_queried_fields":{"items":{"$ref":"#/components/schemas/FieldQueryMetrics"},"type":"array","title":"Most Queried Fields","description":"Most frequently queried fields"},"slowest_fields":{"items":{"$ref":"#/components/schemas/FieldPerformanceMetrics"},"type":"array","title":"Slowest Fields","description":"Fields with highest latency"},"compound_indexes":{"items":{"$ref":"#/components/schemas/CompoundIndexPattern"},"type":"array","title":"Compound Indexes","description":"Compound index opportunities"}},"type":"object","required":["namespace_id","time_range_days","summary","recommendations","most_queried_fields","slowest_fields","compound_indexes"],"title":"NamespaceSummaryResponse","description":"Comprehensive namespace analytics summary."},"NamespaceType":{"type":"string","enum":["standard","marketplace"],"title":"NamespaceType","description":"Type of namespace defining its access control and billing model."},"Notification":{"properties":{"id":{"type":"string","title":"Id","description":"Unique ID"},"type":{"$ref":"#/components/schemas/NotificationType","description":"Notification type"},"priority":{"$ref":"#/components/schemas/NotificationPriority","description":"Priority level"},"title":{"type":"string","title":"Title","description":"Notification title"},"content":{"type":"string","title":"Content","description":"Notification content"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"organization_id":{"type":"string","title":"Organization Id","description":"Organization ID"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID (if applicable)"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional metadata"},"delivery_status":{"additionalProperties":{"type":"string"},"propertyNames":{"$ref":"#/components/schemas/NotificationChannel"},"type":"object","title":"Delivery Status","description":"Delivery status by channel"},"read":{"type":"boolean","title":"Read","description":"Whether the notification has been read","default":false},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At","description":"When the notification was read"}},"type":"object","required":["type","priority","title","content","organization_id"],"title":"Notification","description":"Model for a notification instance."},"NotificationChannel":{"type":"string","enum":["email","slack","webhook"],"title":"NotificationChannel","description":"Enum for notification delivery channels."},"NotificationChannelConfig":{"properties":{"channel_type":{"type":"string","title":"Channel Type","description":"Type of notification channel: 'webhook', 'slack', 'email'","examples":["webhook","slack","email"]},"channel_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Id","description":"Reference to a pre-configured notification channel in the organization","examples":["wh_safety_team","sl_alerts","em_security"]},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","description":"Channel-specific configuration overrides (e.g., webhook URL, Slack channel)","examples":[{"url":"https://example.com/webhook"},{"channel":"#alerts"},{"to":["admin@example.com"]}]}},"type":"object","required":["channel_type"],"title":"NotificationChannelConfig","description":"Configuration for a notification channel.\n\nChannels define where notifications are sent when an alert is triggered.\nSupports multiple channel types including webhooks, Slack, and email.\n\nAttributes:\n channel_type: Type of notification channel (webhook, slack, email)\n channel_id: Optional reference to a pre-configured channel in the organization\n config: Optional channel-specific configuration overrides"},"NotificationContentType":{"type":"string","enum":["plain_text","html","markdown","json"],"title":"NotificationContentType","description":"Enum for content formats."},"NotificationPriority":{"type":"string","enum":["low","medium","high","critical"],"title":"NotificationPriority","description":"Enum for notification priority levels."},"NotificationType":{"type":"string","enum":["pipeline_success","pipeline_failure","feature_extraction_success","feature_extraction_failure","system_alert","billing_alert","quota_alert","audit_alert","maintenance_alert","custom","onboarding_nudge","engagement_nudge","feature_tip"],"title":"NotificationType","description":"Enum for notification types."},"OPTICSParams":{"properties":{"min_samples":{"type":"integer","minimum":2.0,"title":"Min Samples","description":"Number of samples in a neighborhood for a point to be considered a core point","default":5},"max_eps":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Max Eps","description":"Maximum distance between two samples. Default (None) means no maximum distance"},"metric":{"type":"string","title":"Metric","description":"Metric to use for distance computation","default":"minkowski"},"p":{"type":"number","exclusiveMinimum":0.0,"title":"P","description":"Parameter for the Minkowski metric","default":2},"metric_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metric Params","description":"Additional keyword arguments for the metric function"},"cluster_method":{"type":"string","title":"Cluster Method","description":"Method to extract clusters ('xi' or 'dbscan')","default":"xi"},"eps":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Eps","description":"Maximum distance for DBSCAN cluster extraction method"},"xi":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Xi","description":"Minimum steepness on the reachability plot for cluster boundary (xi method)","default":0.05},"predecessor_correction":{"type":"boolean","title":"Predecessor Correction","description":"Correct clusters based on predecessors (xi method)","default":true},"min_cluster_size":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Cluster Size","description":"Minimum number of samples in a cluster. Can be a fraction if < 1.0"},"algorithm":{"type":"string","title":"Algorithm","description":"Algorithm to compute pointwise distances ('auto', 'ball_tree', 'kd_tree', 'brute')","default":"auto"},"leaf_size":{"type":"integer","minimum":1.0,"title":"Leaf Size","description":"Leaf size passed to BallTree or KDTree","default":30},"n_jobs":{"type":"integer","title":"N Jobs","description":"Number of parallel jobs to run (-1 means using all processors)","default":1}},"type":"object","title":"OPTICSParams","description":"Parameters for OPTICS clustering algorithm."},"ObjectAggregationRequest":{"properties":{"group_by":{"items":{"$ref":"#/components/schemas/GroupByField"},"type":"array","minItems":1,"title":"Group By","description":"Fields to group results by. REQUIRED, at least one field. Can include field transformations (date_trunc, date_part). Results will have one row per unique combination of group_by values."},"aggregations":{"items":{"$ref":"#/components/schemas/AggregationOperation"},"type":"array","minItems":1,"title":"Aggregations","description":"Aggregation operations to perform. REQUIRED, at least one operation. Each operation produces a calculated field in results. Can combine multiple functions (COUNT, SUM, AVG, etc.)."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY.","examples":[{"metadata.status":"active"},{"created_at":{"$gte":"2024-01-01"},"metadata.type":"video"}]},"having":{"anyOf":[{"items":{"$ref":"#/components/schemas/HavingCondition"},"type":"array"},{"type":"null"}],"title":"Having","description":"Post-aggregation filters to apply to results. OPTIONAL, filters groups after aggregation. Uses aggregation aliases as field names. Applied after GROUP BY and aggregation calculations."},"unwind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unwind","description":"Array field to unwind before aggregation. OPTIONAL, creates one document per array element. Useful for aggregating over array contents. Example: 'blobs' to analyze each blob separately.","examples":["blobs","metadata.tags","metadata.categories"]},"range_buckets":{"anyOf":[{"items":{"$ref":"#/components/schemas/RangeBucket"},"type":"array"},{"type":"null"}],"title":"Range Buckets","description":"Range-based bucketing for numeric fields. OPTIONAL, creates histogram-style buckets. Groups numeric values into defined ranges. Applied during grouping stage."},"sort_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By","description":"Field to sort results by. OPTIONAL, can be group_by field or aggregation alias. Defaults to no specific order. Use with sort_direction to control order.","examples":["total_count","avg_duration","category"]},"sort_direction":{"type":"string","title":"Sort Direction","description":"Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field.","default":"desc","examples":["asc","desc"]},"limit":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Limit","description":"Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries.","examples":[10,50,100]}},"type":"object","required":["group_by","aggregations"],"title":"ObjectAggregationRequest","description":"Aggregation request for bucket objects.\n\nExtends the base AggregationRequest with object-specific context.\nInherits all fields from AggregationRequest.\n\nRequirements:\n - group_by: REQUIRED, fields to group by\n - aggregations: REQUIRED, aggregation operations to perform\n - All other fields from AggregationRequest are available\n\nExamples:\n - Count objects by status\n - Daily upload statistics\n - Category-based analytics with filtering","examples":[{"aggregations":[{"alias":"total","function":"count"}],"description":"Count objects by status","group_by":[{"alias":"status","field":"status"}],"sort_by":"total","sort_direction":"desc"},{"aggregations":[{"alias":"uploads","function":"count"},{"alias":"unique_users","distinct_field":"metadata.user_id","function":"count_distinct"}],"description":"Daily upload statistics","group_by":[{"alias":"date","date_trunc":"day","field":"created_at"}],"sort_by":"date","sort_direction":"asc"},{"aggregations":[{"alias":"count","function":"count"},{"alias":"total_size","field":"metadata.size","function":"sum"},{"alias":"avg_size","field":"metadata.size","function":"avg"}],"description":"Content type distribution with size stats","group_by":[{"alias":"type","field":"content_type"}],"having":[{"field":"count","operator":"gte","value":5}],"sort_by":"total_size","sort_direction":"desc"}]},"ObjectAggregationResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AggregationResult"},"type":"array","title":"Results","description":"List of aggregation results, one per group."},"total_groups":{"type":"integer","title":"Total Groups","description":"Total number of unique groups returned."},"query_info":{"additionalProperties":true,"type":"object","title":"Query Info","description":"Additional information about the query execution. May include pipeline stages, execution time, etc."}},"type":"object","required":["results","total_groups"],"title":"ObjectAggregationResponse","description":"Response containing object aggregation results.\n\nReturns aggregated statistics grouped by specified fields.","examples":[{"query_info":{"execution_time_ms":45,"pipeline_stages":5},"results":[{"group":{"status":"completed"},"metrics":{"total":1523}},{"group":{"status":"pending"},"metrics":{"total":87}}],"total_groups":2}]},"ObjectListStats":{"properties":{"total_objects":{"type":"integer","title":"Total Objects","description":"Total number of objects in the result","default":0},"total_blobs":{"type":"integer","title":"Total Blobs","description":"Total number of blobs across all objects","default":0},"avg_blobs_per_object":{"type":"number","title":"Avg Blobs Per Object","description":"Average number of blobs per object","default":0.0},"objects_by_status":{"additionalProperties":true,"type":"object","title":"Objects By Status","description":"Count of objects grouped by status"}},"type":"object","title":"ObjectListStats","description":"Aggregate statistics for a list of objects."},"ObjectResponse":{"properties":{"object_id":{"type":"string","title":"Object Id","description":"Unique identifier for the object"},"bucket_id":{"type":"string","title":"Bucket Id","description":"ID of the bucket this object belongs to"},"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Prefix","description":"Storage key/path of the object, this will be used to retrieve the object from the storage. It is similar to a file path. If not provided, it will be placed in the root of the bucket."},"blobs":{"items":{"$ref":"#/components/schemas/BlobModel"},"type":"array","title":"Blobs","description":"List of blobs contained in this object"},"source_details":{"items":{"$ref":"#/components/schemas/SourceDetails"},"type":"array","title":"Source Details","description":"Lineage/source details for this object; used for downstream references."},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"The current status of the object.","default":"DRAFT"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"The error message if the object failed to process.","examples":["Failed to process object: Object not found"]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the object was created. Automatically populated by the system."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Timestamp when the object was last updated. Automatically populated by the system."},"document_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Document Count","description":"Number of documents produced from this object across all collections. Populated on GET requests. Null on list responses (expensive query). Use this to check if an object has already been processed."}},"additionalProperties":true,"type":"object","required":["bucket_id"],"title":"ObjectResponse","description":"Response model for bucket objects.","examples":[{"blobs":[{"blob_id":"blob_1","data":{"num_pages":5,"title":"Service Agreement 2024"},"key_prefix":"/contract-2024/content.pdf","metadata":{"author":"John Doe","department":"Legal"},"property":"content","type":"PDF"}],"bucket_id":"bkt_9xy8z7","content_hash":"28a9f5e8...","created_at":"2024-10-21T10:30:00Z","key_prefix":"/contract-2024","metadata":{"category":"contracts","year":2024},"object_id":"obj_123abc456def","skip_duplicates":false,"status":"DRAFT","updated_at":"2024-10-21T10:30:00Z"}]},"OffsetPaginationParams":{"properties":{"method":{"$ref":"#/components/schemas/PaginationMethod","description":"Constant identifying offset pagination (REQUIRED).","default":"offset"},"page_size":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Page Size","description":"Number of documents per page (REQUIRED). Default: 10.","default":10},"page_number":{"type":"integer","minimum":1.0,"title":"Page Number","description":"1-based page index to retrieve (REQUIRED). Default: 1.","default":1}},"type":"object","title":"OffsetPaginationParams","description":"Offset-based pagination using page number sizing.\n\nBest for: Traditional page UIs with page number navigation\n\nHow it works:\n- Uses page numbers (1, 2, 3...) and page size\n- Calculates offset as: (page_number - 1) * page_size\n- Simple and familiar for users\n- Can jump to any page directly\n\nTradeoffs:\n- Can have \"page drift\" if data changes between requests\n- Example: Items added/deleted causes duplicates or gaps\n- Less efficient for large offsets (database must skip N rows)\n\nUse when:\n- Building traditional page-numbered UIs\n- Users need to jump to specific pages\n- Result set is relatively stable\n- Working with smaller datasets\n\nExample:\nPage 1: {\"method\": \"offset\", \"page_size\": 25, \"page_number\": 1}\nPage 2: {\"method\": \"offset\", \"page_size\": 25, \"page_number\": 2}"},"OpenAIModel":{"type":"string","enum":["gpt-4o-2024-08-06","gpt-4o-mini-2024-07-18","gpt-4.1-2025-04-14","gpt-4.1-mini-2025-04-14","o3-mini-2025-01-31"],"title":"OpenAIModel","description":"OpenAI model identifiers for LLM generation.\n\nModels listed in order of capability and cost (highest to lowest).\nAll models support vision (images) except O3-mini.\n\nValues:\n GPT_4O: Latest GPT-4 Omni model (2024-08-06)\n - Use for: Production, highest quality generation\n - Context: 128K tokens\n - Vision: Yes\n - Cost: $2.50/1M input, $10/1M output\n - Performance: 200-500ms per request\n - When to use: Need best quality, willing to pay premium\n\n GPT_41: GPT-4.1 (2025-04-14)\n - Use for: Future-proofed pipelines\n - Context: 128K tokens\n - Vision: Yes\n - Cost: TBD (expected similar to GPT-4o)\n - When to use: Want latest model features\n\n GPT_4O_MINI: Smaller, faster GPT-4 Omni (2024-07-18)\n - Use for: High-volume, cost-sensitive workloads\n - Context: 128K tokens\n - Vision: Yes\n - Cost: $0.15/1M input, $0.60/1M output\n - Performance: 100-200ms per request\n - When to use: Good balance of quality and cost\n\n GPT_41_MINI: Smaller GPT-4.1 (2025-04-14)\n - Use for: Future cost-optimized pipelines\n - Context: 128K tokens\n - Vision: Yes\n - Cost: TBD (expected similar to GPT-4o-mini)\n - When to use: Want latest features at lower cost\n\n O3_MINI: Reasoning-optimized model (2025-01-31)\n - Use for: Complex reasoning, math, code\n - Context: 200K tokens\n - Vision: No\n - Cost: TBD\n - When to use: Need advanced reasoning capabilities\n\nExamples:\n - Use GPT_4O for caption generation with images (best quality)\n - Use GPT_4O_MINI for high-volume video scene summarization (cost-effective)\n - Use O3_MINI for complex entity extraction requiring reasoning"},"OrgModelDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"model_id":{"type":"string","title":"Model Id"},"message":{"type":"string","title":"Message"}},"type":"object","required":["model_id","message"],"title":"OrgModelDeleteResponse","description":"Response model for org model deletion."},"OrgModelDeploymentInfo":{"properties":{"ray_cluster_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Cluster Url","description":"Ray cluster URL where model is deployed"},"ray_deployment_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Deployment Name","description":"Ray deployment name"},"deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployed At","description":"When the model was deployed"}},"type":"object","title":"OrgModelDeploymentInfo","description":"Deployment information for an org-level model."},"OrgModelDetailResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"model":{"$ref":"#/components/schemas/OrgModelDocument"}},"type":"object","required":["model"],"title":"OrgModelDetailResponse","description":"Response model for org model details."},"OrgModelDocument":{"properties":{"model_id":{"type":"string","title":"Model Id","description":"Unique model identifier"},"organization_id":{"type":"string","title":"Organization Id","description":"Owner organization ID"},"name":{"type":"string","title":"Name","description":"Model name"},"version":{"type":"string","title":"Version","description":"Model version (semver)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Model description"},"s3_archive_url":{"type":"string","title":"S3 Archive Url","description":"S3 URL to model archive"},"model_format":{"type":"string","enum":["safetensors","onnx","pytorch","huggingface"],"title":"Model Format","description":"Model format/framework"},"model_hash":{"type":"string","title":"Model Hash","description":"SHA256 hash of model archive"},"validation_status":{"type":"string","enum":["passed","failed","pending"],"title":"Validation Status","description":"Validation status"},"validation_errors":{"items":{"type":"string"},"type":"array","title":"Validation Errors","description":"Validation error messages"},"deployed":{"type":"boolean","title":"Deployed","description":"Whether model has been deployed to any namespace","default":false},"deployment_info":{"anyOf":[{"$ref":"#/components/schemas/OrgModelDeploymentInfo"},{"type":"null"}],"description":"Deployment details"},"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)"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"Input schema JSON"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"Output schema JSON"},"resource_requirements":{"$ref":"#/components/schemas/ModelResourceRequirements","description":"Resource requirements for deployment"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"}},"type":"object","required":["model_id","organization_id","name","version","s3_archive_url","model_format","model_hash","validation_status"],"title":"OrgModelDocument","description":"Org-level model document stored in MongoDB.\n\nOrg-scoped: Uses organization_id instead of namespace_id.\nModels belong to an organization and can be enabled in any namespace within that org."},"OrgModelListItem":{"properties":{"model_id":{"type":"string","title":"Model Id"},"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"model_format":{"type":"string","enum":["safetensors","onnx","pytorch","huggingface"],"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"},"deployed":{"type":"boolean","title":"Deployed"},"validation_status":{"type":"string","title":"Validation Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["model_id","name","version","model_format","deployed","validation_status","created_at","updated_at"],"title":"OrgModelListItem","description":"Model item in list response."},"OrgModelListResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"models":{"items":{"$ref":"#/components/schemas/OrgModelListItem"},"type":"array","title":"Models"},"total":{"type":"integer","title":"Total"},"organization_id":{"type":"string","title":"Organization Id"}},"type":"object","required":["models","total","organization_id"],"title":"OrgModelListResponse","description":"Response model for listing org models."},"OrganizationAdminUpdateRequest":{"properties":{"account_type":{"anyOf":[{"$ref":"#/components/schemas/AccountTier"},{"type":"null"}],"description":"Update organization billing tier."},"rate_limits":{"anyOf":[{"$ref":"#/components/schemas/BaseRateLimits"},{"type":"null"}],"description":"Override rate limits for the organization."},"infrastructure":{"anyOf":[{"$ref":"#/components/schemas/OrganizationInfrastructure"},{"type":"null"}],"description":"šŸ”’ ADMIN ONLY: Configure dedicated infrastructure (Qdrant/Ray). This field is ONLY accessible via private admin endpoints with MIXPEEK_PRIVATE_TOKEN. NOT exposed in public API responses. NOT modifiable by organization users. Used for ENTERPRISE customers with dedicated infrastructure."}},"type":"object","title":"OrganizationAdminUpdateRequest","description":"Admin-only update payload for organization.\n\nSecurity: This model is ONLY used by private admin endpoints that require\nMIXPEEK_PRIVATE_TOKEN authentication. Regular users cannot access or modify\nthese fields, especially infrastructure configuration."},"OrganizationInfrastructure":{"properties":{"qdrant_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qdrant Url","description":"Dedicated Qdrant instance URL for this organization. When set, all requests from this organization route to this Qdrant instance. Format: http://hostname:port or https://hostname:port. REQUIRED for ENTERPRISE tier with dedicated infrastructure. NOT REQUIRED for SHARED tier (uses settings.QDRANT_URL).","examples":["http://qdrant-acme-prod:6333","https://qdrant.acme.com:6333"]},"qdrant_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qdrant Api Key","description":"API key for dedicated Qdrant instance. REQUIRED when qdrant_url is set. NOT REQUIRED for shared tier.","examples":["qdrant_key_abc123xyz789"]},"ray_head_node_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Head Node Url","description":"Dedicated Ray cluster head node URL for job submission. Format: ray://hostname:port. REQUIRED for ENTERPRISE tier with dedicated Ray cluster. NOT REQUIRED for SHARED tier (uses settings.RAY_ADDRESS).","examples":["ray://ray-head-acme-prod:10001","ray://ray-cluster.acme.com:10001"]},"ray_dashboard_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Dashboard Url","description":"Ray dashboard URL for monitoring and job submission. Format: http://hostname:port. REQUIRED for ENTERPRISE tier with dedicated Ray cluster. NOT REQUIRED for SHARED tier.","examples":["http://ray-dashboard-acme-prod:8265","https://ray-dashboard.acme.com:8265"]},"compute_tier":{"$ref":"#/components/schemas/ComputeTier","description":"Default compute tier for all namespaces in this organization. Individual namespaces can override this setting. SHARED: Multi-tenant Mixpeek infrastructure. DEDICATED_CPU: Single-tenant CPU compute. DEDICATED_GPU: Single-tenant GPU compute.","default":"shared"}},"type":"object","title":"OrganizationInfrastructure","description":"Infrastructure configuration for an organization.\n\nDefines dedicated infrastructure resources for ENTERPRISE tier organizations.\nWhen configured, all namespaces in the organization inherit these settings\nunless explicitly overridden at the namespace level.\n\nMulti-Tenant Architecture:\n SHARED (FREE/PRO tiers):\n - Uses Mixpeek's shared Qdrant instance (settings.QDRANT_URL)\n - Uses Mixpeek's shared Ray cluster (settings.RAY_ADDRESS)\n - infrastructure field is None or not configured\n\n DEDICATED (ENTERPRISE tier):\n - Uses organization's dedicated Qdrant instance\n - Uses organization's dedicated Ray cluster\n - infrastructure field is configured with dedicated endpoints\n\nNamespace Override:\n Individual namespaces can override organization defaults by configuring\n their own infrastructure settings in NamespaceInfrastructure.\n\nExamples:\n - FREE/PRO org: infrastructure=None (uses shared)\n - ENTERPRISE org: infrastructure configured with dedicated URLs\n - ENTERPRISE org namespace override: namespace.infrastructure overrides org.infrastructure","examples":[{"compute_tier":"shared","description":"SHARED tier organization (FREE/PRO)"},{"compute_tier":"dedicated_cpu","description":"ENTERPRISE tier with dedicated infrastructure","qdrant_api_key":"qdrant_key_abc123","qdrant_url":"http://qdrant-acme-prod:6333","ray_dashboard_url":"http://ray-dashboard-acme-prod:8265","ray_head_node_url":"ray://ray-head-acme-prod:10001"},{"compute_tier":"dedicated_gpu","description":"ENTERPRISE tier with GPU cluster","qdrant_api_key":"qdrant_key_xyz789","qdrant_url":"https://qdrant.acme.com:6333","ray_dashboard_url":"https://ray-gpu-dashboard.acme.com:8265","ray_head_node_url":"ray://gpu-cluster.acme.com:10001"}]},"OrganizationModel":{"properties":{"internal_id":{"type":"string","title":"Internal Id","description":"Internal organization identifier for multi-tenancy. High-entropy secret (24 chars) used exclusively for database queries and tenant isolation. This ID is immutable and never exposed in user-facing contexts. Format: int_xxxxxxxxxxxxxxxxxxxxx. USAGE: Database scoping, service initialization, provider configuration.","examples":["int_abc123def456ghi789jkl012mno345pqr678"]},"organization_id":{"type":"string","title":"Organization Id","description":"Public organization identifier exposed in APIs and user-facing contexts. Lower-entropy ID (15 chars) safe for logs, error messages, and API responses. This ID can be changed for rebranding without affecting backend operations. Format: org_xxxxxxxxxxxxx. USAGE: API responses, error messages, logs, support tickets, analytics.","examples":["org_demo123","org_acme"]},"auth_provider_org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Provider Org Id","description":"External auth provider's organization identifier (e.g., PropelAuth org ID). Used as a stable lookup key that doesn't depend on organization name matching. Set at org creation time and never changes."},"organization_name":{"type":"string","title":"Organization Name","description":"Display name of the organization."},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"URL to organization's logo image. Automatically fetched from Google's favicon service based on user's email domain during org creation. Can be overridden with custom URL. Format: https://www.google.com/s2/favicons?domain=... or custom URL.","examples":["https://www.google.com/s2/favicons?domain=stripe.com&sz=128","https://www.google.com/s2/favicons?domain=github.com&sz=128","https://example.com/logos/company.png"]},"account_type":{"$ref":"#/components/schemas/AccountTier","description":"Billing tier determining available features and limits.","default":"free"},"credit_count":{"type":"integer","title":"Credit Count","description":"DEPRECATED: Legacy credit balance. Use current_month_usage instead.","default":0},"free_tier_usage_limit":{"type":"integer","title":"Free Tier Usage Limit","description":"Maximum usage allowed before payment method required. Once current_month_usage exceeds this AND auto_billing is disabled, API access is blocked until payment method is added.","default":1000},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Custom metadata applied to the organization."},"billing_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Billing Email","description":"Email address for invoices and billing notifications."},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id","description":"Stripe Customer ID for usage-based billing. Created when organization sets up payment method. Format: cus_xxxxxxxxxxxxx","examples":["cus_abc123def456"]},"default_payment_method_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Payment Method Id","description":"Default Stripe PaymentMethod ID for automatic monthly billing. Set when organization attaches a payment method. Format: pm_xxxxxxxxxxxxx","examples":["pm_1ABC2DEF3GHI"]},"auto_billing_enabled":{"type":"boolean","title":"Auto Billing Enabled","description":"Whether automatic monthly billing is enabled. When True, organization is charged automatically at end of month for usage. When False, organization uses manual credit purchases (legacy mode).","default":false},"billing_cycle_start":{"type":"integer","maximum":31.0,"minimum":1.0,"title":"Billing Cycle Start","description":"Day of month when billing cycle starts (1-31). Invoices are generated on this day each month. If day doesn't exist in month (e.g., 31 in Feb), uses last day of month.","default":1},"current_month_usage":{"type":"integer","title":"Current Month Usage","description":"Credits consumed in current billing cycle. Reset to 0 after invoice generation. Used for real-time usage display in dashboard.","default":0},"last_invoice_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Invoice Date","description":"UTC timestamp of last invoice generation. Used to determine billing period and prevent duplicate invoices."},"billing_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Billing Period Start","description":"UTC timestamp when current billing period started. Set when invoice is generated or billing enabled."},"monthly_spending_budget":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Spending Budget","description":"Soft spending limit in USD cents for the current billing cycle. When set, triggers alerts at specified thresholds but doesn't block API access. Example: 10000 = $100 budget. None = no budget limit (unlimited spending allowed).","examples":[10000,50000,100000]},"spending_alert_thresholds":{"items":{"type":"integer"},"type":"array","title":"Spending Alert Thresholds","description":"Percentage thresholds for spending alerts (0-100). When current spending reaches each threshold, an alert is sent. Default: [50, 75, 90, 100] sends alerts at 50%, 75%, 90%, and 100% of budget. Only applies when monthly_spending_budget is set."},"spending_alerts_enabled":{"type":"boolean","title":"Spending Alerts Enabled","description":"Whether to send spending alerts when thresholds are crossed. When False, no alerts are sent even if thresholds are exceeded.","default":true},"spending_alerts_sent":{"items":{"type":"integer"},"type":"array","title":"Spending Alerts Sent","description":"Track which alert thresholds have been triggered in current billing cycle. Prevents duplicate alert notifications. Reset to empty list when invoice is generated. Example: [50, 75] means 50% and 75% alerts have been sent."},"hard_spending_cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Hard Spending Cap","description":"Hard spending limit in USD cents for the current billing cycle. When reached, API access is blocked (similar to free tier limit). Example: 100000 = $1000 hard cap. None = no hard cap (only soft alerts apply). IMPORTANT: When enabled, operations are rejected once cap is reached.","examples":[50000,100000,500000]},"hard_cap_enabled":{"type":"boolean","title":"Hard Cap Enabled","description":"Whether to enforce the hard spending cap. When True and hard_spending_cap is set, API access is blocked at cap. When False, hard_spending_cap is ignored (only soft alerts apply). Users must explicitly enable this for protection.","default":false},"rate_limits":{"$ref":"#/components/schemas/BaseRateLimits","description":"Effective rate-limit configuration for the organization."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC timestamp when the organization was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"UTC timestamp of the most recent organization update."},"users":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Users","description":"Deprecated nested user documents (maintained for backwards compatibility during migration)."},"infrastructure":{"anyOf":[{"$ref":"#/components/schemas/OrganizationInfrastructure"},{"type":"null"}],"description":"Infrastructure configuration for dedicated resources. None for SHARED tier (FREE/PRO organizations using Mixpeek infrastructure). Configured for ENTERPRISE tier with dedicated Qdrant/Ray instances. Inherited by all namespaces unless overridden at namespace level."},"max_dedicated_clusters":{"type":"integer","minimum":0.0,"title":"Max Dedicated Clusters","description":"Maximum number of dedicated infrastructure clusters allowed for this organization. 0 for non-enterprise tiers (FREE, STARTER, PROFESSIONAL). Set based on enterprise tier package (e.g., 3, 5, 10, unlimited). Each cluster includes dedicated Anyscale/Ray compute + Qdrant database.","default":0,"examples":[0,3,5,10]},"max_active_batches":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Active Batches","description":"Legacy field ā€” kept for backward compatibility. Enforcement has moved to max_concurrent_ray_jobs. When null, uses tier-based defaults.","examples":[1,3,5,10]},"max_concurrent_ray_jobs":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Concurrent Ray Jobs","description":"Maximum number of concurrent Ray Jobs (actively processing batches). This is the real resource bottleneck ā€” each Ray Job consumes cluster actors. Batches in PENDING status (queued in Celery) don't count. When null, uses tier-based defaults: Free=1, Pro=3, Team=5, Enterprise=20. Set explicitly to override the tier default.","examples":[1,3,5,20]},"dedicated_cluster_ids":{"items":{"type":"string"},"type":"array","title":"Dedicated Cluster Ids","description":"List of dedicated infrastructure cluster IDs owned by this organization. Only applicable for Enterprise tier. Format: iclstr_xxxxxxxxxxxxx","examples":[[],["iclstr_abc123xyz","iclstr_def456uvw"]]},"secrets":{"additionalProperties":{"type":"string"},"type":"object","title":"Secrets","description":"Encrypted secrets vault for API integrations and external service credentials. Keys are secret names (e.g., 'stripe_api_key', 'github_token'), values are encrypted strings stored using Fernet encryption. Used by api_call retriever stage for secure credential storage. Secrets are encrypted on write and decrypted on read using ENCRYPTION_KEY. NEVER expose decrypted values in API responses or logs. Note: Values are stored as encrypted strings (bytes), not EncryptedStr type.","examples":[{"stripe_api_key":"gAAAAABf8x7...encrypted_data"},{"github_token":"gAAAAABf8x7...encrypted_data","weather_api_key":"gAAAAABf8x7...encrypted_data"}]},"audit_settings":{"$ref":"#/components/schemas/AuditSettings","description":"Audit trail configuration for the organization. Controls whether read operations are logged to the audit trail. By default, only write operations (create, update, delete) are audited."}},"type":"object","required":["organization_name"],"title":"OrganizationModel","description":"Organization document representing a tenant in the multi-tenant system.\n\nMulti-Tenancy Architecture:\n Organizations are the root tenant in Mixpeek's multi-tenant architecture.\n Each organization has dual identifiers optimized for different purposes:\n\n - internal_id: Backend tenant isolation (database queries, scoping)\n - organization_id: Frontend/user-facing identifier (APIs, logs, support)\n\nID Usage Patterns:\n Database Queries:\n āœ… service = CollectionService(internal_id=org.internal_id)\n āŒ service = CollectionService(internal_id=org.organization_id) # Wrong!\n\n Error Messages:\n āœ… raise NotFoundError(details={\"organization_id\": org.organization_id})\n āŒ raise NotFoundError(details={\"internal_id\": org.internal_id}) # Don't expose!\n\n Logging:\n āœ… logger.info(f\"Action for org {org.organization_id}\", extra={\"internal_id\": org.internal_id})\n āŒ logger.info(f\"Action for org {org.internal_id}\") # Not user-friendly!\n\nSecurity Model:\n - internal_id is HIGH-ENTROPY (24 chars) and treated as a secret\n - organization_id is LOWER-ENTROPY (15 chars) and safe to expose\n - Never expose internal_id in API responses or user-facing messages","examples":[{"account_type":"pro","billing_email":"billing@acme.com","created_at":"2025-01-01T00:00:00Z","credit_count":250000,"internal_id":"int_x1y2z3","metadata":{"region":"us-east-1"},"organization_id":"org_demo123","organization_name":"Acme Corporation","updated_at":"2025-01-01T00:00:00Z"}]},"OrganizationModelResponse":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"organization_name":{"type":"string","title":"Organization Name"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url"},"account_type":{"$ref":"#/components/schemas/AccountTier"},"credit_count":{"type":"integer","title":"Credit Count"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"billing_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Billing Email"},"rate_limits":{"$ref":"#/components/schemas/BaseRateLimits"},"auto_billing_enabled":{"type":"boolean","title":"Auto Billing Enabled","default":false},"billing_cycle_start":{"type":"integer","title":"Billing Cycle Start","default":1},"current_month_usage":{"type":"integer","title":"Current Month Usage","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"users":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Users"}},"type":"object","required":["organization_id","organization_name","account_type","credit_count","rate_limits","created_at","updated_at"],"title":"OrganizationModelResponse","description":"Response model for organization endpoints.\n\nSECURITY: Does NOT expose internal_id to prevent leakage of high-entropy secrets.\nOnly organization_id (public identifier) is included in API responses.","examples":[{"account_type":"pro","created_at":"2025-01-01T00:00:00Z","credit_count":250000,"logo_url":"https://www.google.com/s2/favicons?domain=acme.com&sz=128","organization_id":"org_demo123","organization_name":"Acme Corporation"}]},"OrganizationPublishStatsResponse":{"properties":{"current_count":{"type":"integer","title":"Current Count","description":"Number of currently published retrievers"},"max_allowed":{"type":"integer","title":"Max Allowed","description":"Maximum number of allowed published retrievers"},"remaining":{"type":"integer","title":"Remaining","description":"Number of remaining publish slots"},"at_limit":{"type":"boolean","title":"At Limit","description":"Whether the organization has reached the publish limit"}},"type":"object","required":["current_count","max_allowed","remaining","at_limit"],"title":"OrganizationPublishStatsResponse","description":"Response for organization publish quota stats."},"OrganizationUpdateRequest":{"properties":{"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name","description":"Updated display name for the organization."},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Updated organization logo URL (e.g., custom logo to override auto-generated logo)."},"billing_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Billing Email","description":"Updated billing contact email."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Replace metadata with provided dictionary when set."},"rate_limits":{"anyOf":[{"$ref":"#/components/schemas/BaseRateLimits"},{"type":"null"}],"description":"Override the computed rate limits for the organization."}},"type":"object","title":"OrganizationUpdateRequest","description":"Partial update payload for organization metadata."},"PageMeta":{"properties":{"title":{"type":"string","title":"Title","description":"Page title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Page description"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Logo URL"},"favicon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon Url","description":"Favicon URL"}},"type":"object","required":["title"],"title":"PageMeta","description":"Page-level metadata."},"PageResponse":{"properties":{"page_id":{"type":"string","title":"Page Id"},"slug":{"type":"string","title":"Slug"},"template":{"type":"string","title":"Template"},"sections":{"items":{"$ref":"#/components/schemas/SectionConfig"},"type":"array","title":"Sections"},"custom_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Html"},"meta":{"$ref":"#/components/schemas/PageMeta"},"hero":{"anyOf":[{"$ref":"#/components/schemas/HeroConfig"},{"type":"null"}]},"theme":{"$ref":"#/components/schemas/ThemeConfig"},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}]},"stats":{"items":{"$ref":"#/components/schemas/StatItem"},"type":"array","title":"Stats"},"featured_gallery":{"anyOf":[{"$ref":"#/components/schemas/FeaturedGalleryConfig-Output"},{"type":"null"}]},"tabs":{"items":{"$ref":"#/components/schemas/PageTab-Output"},"type":"array","title":"Tabs"},"password_protected":{"type":"boolean","title":"Password Protected"},"is_active":{"type":"boolean","title":"Is Active"},"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":["page_id","slug","template","sections","custom_html","meta","hero","theme","seo","stats","featured_gallery","tabs","password_protected","is_active","created_at","updated_at"],"title":"PageResponse","description":"Response model for a Page."},"PageTab-Input":{"properties":{"tab_id":{"type":"string","title":"Tab Id","description":"Unique identifier for this tab"},"label":{"type":"string","title":"Label","description":"Display label for the tab"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Internal retriever ID (use for private retrievers)"},"public_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Name","description":"Marketplace catalog public_name (proxies execution via public API)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional tab description shown as subtitle"},"display_config":{"$ref":"#/components/schemas/DisplayConfig-Input","description":"Display configuration for this tab's search UI"}},"type":"object","required":["tab_id","label","display_config"],"title":"PageTab","description":"A single tab in a Page."},"PageTab-Output":{"properties":{"tab_id":{"type":"string","title":"Tab Id","description":"Unique identifier for this tab"},"label":{"type":"string","title":"Label","description":"Display label for the tab"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Internal retriever ID (use for private retrievers)"},"public_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Name","description":"Marketplace catalog public_name (proxies execution via public API)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional tab description shown as subtitle"},"display_config":{"$ref":"#/components/schemas/DisplayConfig-Output","description":"Display configuration for this tab's search UI"}},"type":"object","required":["tab_id","label","display_config"],"title":"PageTab","description":"A single tab in a Page."},"PaginationMetadata":{"properties":{"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of records"},"limit":{"type":"integer","minimum":0.0,"title":"Limit","description":"Requested page size"},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Offset applied to query"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether additional pages exist"}},"type":"object","required":["total","limit","offset","has_next"],"title":"PaginationMetadata","description":"Pagination metadata envelope."},"PaginationMethod":{"type":"string","enum":["offset","cursor","scroll","keyset"],"title":"PaginationMethod","description":"Supported pagination strategies for retriever execution."},"PaginationResponse":{"properties":{"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page"},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Size"},"total_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Pages"},"next_page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Page"},"previous_page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Page"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","title":"PaginationResponse","description":"PaginationResponse.\n\nCursor-based pagination response:\n- Use next_cursor for navigation\n- Total count fields only populated when include_total=true"},"PatchAlertRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"Updated name for the alert"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Updated description for the alert"},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Updated retriever ID"},"notification_config":{"anyOf":[{"$ref":"#/components/schemas/AlertNotificationConfig"},{"type":"null"}],"description":"Updated notification configuration"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Updated enabled status"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Updated metadata"}},"type":"object","title":"PatchAlertRequest","description":"Request model to update an alert.\n\nAll fields are optional - provide only what you want to update.\nCore fields (retriever_id, notification_config) can be updated since\nalerts don't have join history like taxonomies."},"PatchBatchRequest":{"properties":{"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional user-defined metadata for the batch."}},"type":"object","title":"PatchBatchRequest","description":"Request model for partially updating a batch (PATCH operation)."},"PatchClusterRequest":{"properties":{"cluster_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Name","description":"Updated name for the cluster"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated description for the cluster"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Updated metadata for the cluster"}},"type":"object","title":"PatchClusterRequest","description":"Request model for partially updating a cluster (PATCH operation)."},"PatchDocumentRequest":{"properties":{},"additionalProperties":true,"type":"object","title":"PatchDocumentRequest","description":"Request model for partially updating a document (PATCH operation)."},"PatchNamespaceRequest":{"properties":{"namespace_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Namespace Name","description":"Updated name for the namespace","example":"spotify_playlists_prod"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated description for the namespace"},"payload_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayloadIndexConfig-Input"},"type":"array"},{"type":"null"}],"title":"Payload Indexes","description":"Updated list of custom payload indexes for this namespace."},"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. Default: False.","example":true},"infrastructure":{"anyOf":[{"$ref":"#/components/schemas/NamespaceInfrastructure"},{"type":"null"}],"description":"Infrastructure configuration for this namespace. Set compute_tier to 'dedicated_cpu' or 'dedicated_gpu' and max_custom_models > 0 to enable custom model uploads. Requires Enterprise account."}},"type":"object","title":"PatchNamespaceRequest","description":"Request schema for partially updating a namespace (PATCH operation)."},"PatchObjectRequest":{"properties":{"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Prefix","description":"Updated storage key/path prefix of the object"},"skip_duplicates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Duplicates","description":"Skip duplicate blobs"}},"additionalProperties":true,"type":"object","title":"PatchObjectRequest","description":"Request model for partially updating a bucket object (PATCH operation).\n\nTask 10: Use extra='allow' to accept any user-defined fields at root level.\nNo nested metadata dict - all fields are flat."},"PatchRetrieverRequest":{"properties":{"retriever_name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Retriever Name","description":"Updated retriever name. OPTIONAL - only provide if you want to rename the retriever.","examples":["product_search_v2","customer_lookup_enhanced"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated human-readable description. OPTIONAL - only provide if you want to update the description.","examples":["Enhanced version with better caching","Updated for Q4 2025"]},"visibility":{"anyOf":[{"$ref":"#/components/schemas/RetrieverVisibility"},{"type":"null"}],"description":"Updated visibility level. OPTIONAL - only provide if you want to change the visibility."},"marketplace_listing_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marketplace Listing Id","description":"Updated marketplace listing ID. OPTIONAL - only provide if you want to update the marketplace listing."},"requires_subscription":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Requires Subscription","description":"Updated subscription requirement. OPTIONAL - only provide if you want to change the subscription requirement."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Updated tags for organization and filtering. OPTIONAL - replaces existing tags if provided.","examples":[["production","v2"],["experimental","ml-enhanced"]]},"display_config":{"anyOf":[{"$ref":"#/components/schemas/DisplayConfig-Input"},{"type":"null"}],"description":"Updated display configuration for public retriever UI rendering. OPTIONAL - only provide if you want to update the display settings. Defines how the search interface should appear when published."}},"type":"object","title":"PatchRetrieverRequest","description":"Request to update a retriever's metadata.\n\n**IMPORTANT: Partial Updates with Controlled Mutability**\n\nThis endpoint allows updating ONLY metadata fields. Core retriever logic is immutable\nto ensure consistency for dependent resources (taxonomies, cached results, etc.).\n\n**āœ… Fields You CAN Update (Metadata Only):**\n- `retriever_name`: Rename the retriever\n- `description`: Update documentation\n- `tags`: Update organization tags\n- `display_config`: Update display configuration for publishing\n\n**āŒ Fields You CANNOT Update (Immutable Core Logic):**\n- `input_schema`: Input field definitions (breaks dependent taxonomies)\n- `stages`: Retriever stages and configurations (changes matching behavior)\n- `collection_ids`: Target collections (changes data sources)\n- `budget_limits`: Budget constraints (affects execution behavior)\n\n**Need to Modify Core Logic?**\nUse POST /retrievers/{retriever_id}/clone instead. Cloning creates a new retriever\nwith a new ID, allowing you to:\n- Fix typos in stage names\n- Add or remove stages\n- Change target collections\n- Modify input schema or budget limits\n\n**Behavior:**\n- All fields are OPTIONAL - provide only what you want to update\n- Version number automatically increments on each update\n- Empty updates (no fields provided) will be rejected with 400 error\n- Original retriever remains unchanged (no destructive operations)\n\n**Why This Design?**\n- Taxonomies reference retrievers by ID and expect consistent behavior\n- Cached results remain valid after metadata-only changes\n- Version tracking enables auditing and rollback\n- Published retrievers maintain stable behavior for consumers","examples":[{"example_desc":"Update only the name","name":"product_search_v2"},{"description":"Enhanced with better caching","example_desc":"Update description and tags","tags":["production","cached"]},{"description":"Latest version with improved performance","example_desc":"Update all metadata fields","name":"customer_lookup_v3","tags":["production","optimized","v3"]}]},"PatchRetrieverResponse":{"properties":{"retriever":{"$ref":"#/components/schemas/RetrieverConfig","description":"Updated retriever configuration."}},"type":"object","required":["retriever"],"title":"PatchRetrieverResponse","description":"Response after updating a retriever."},"PatchSessionRequest":{"properties":{"user_memory":{"additionalProperties":true,"type":"object","title":"User Memory","description":"Updated user memory (REQUIRED)"}},"type":"object","required":["user_memory"],"title":"PatchSessionRequest","description":"Request payload for updating session metadata.\n\nOnly user_memory can be updated after session creation.\nTo change agent_config or quotas, create a new session.\n\nAttributes:\n user_memory: Updated user memory/preferences\n\nExample:\n ```python\n request = PatchSessionRequest(\n user_memory={\n \"preferences\": {\"language\": \"es\", \"domain\": \"science\"},\n \"learned_context\": {\"favorite_topics\": [\"AI\", \"robotics\"]}\n }\n )\n ```"},"PatchSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session identifier"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Update timestamp"}},"type":"object","required":["session_id","updated_at"],"title":"PatchSessionResponse","description":"Response for session update.\n\nAttributes:\n session_id: Session identifier\n updated_at: Update timestamp"},"PatchTaxonomyRequest":{"properties":{"taxonomy_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taxonomy Name","description":"Updated name for the taxonomy"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated description for the taxonomy"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Updated metadata for the taxonomy"}},"type":"object","title":"PatchTaxonomyRequest","description":"Request to update a taxonomy's metadata.\n\n**IMPORTANT: Partial Updates with Controlled Mutability**\n\nThis endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable\nto ensure consistency for join history and dependent resources.\n\n**āœ… Fields You CAN Update (Metadata Only):**\n- `taxonomy_name`: Rename the taxonomy\n- `description`: Update documentation\n- `metadata`: Update custom metadata fields\n\n**āŒ Fields You CANNOT Update (Immutable Core Logic):**\n- `config`: Taxonomy configuration (retriever_id, input_mappings, collections, hierarchy)\n- `taxonomy_type`: Type (flat vs hierarchical)\n- `retriever_id`: Associated retriever\n- `input_mappings`: Field mappings\n- `enrichment_fields`: Enrichment configuration\n\n**Need to Modify Core Logic?**\nUse POST /taxonomies/{taxonomy_id}/clone instead. Cloning creates a new taxonomy\nwith a new ID, allowing you to:\n- Change retriever or input mappings\n- Modify enrichment fields\n- Update collection configuration\n- Change taxonomy hierarchy\n\n**Behavior:**\n- All fields are OPTIONAL - provide only what you want to update\n- Empty updates (no fields provided) will be rejected with 400 error\n- Original taxonomy remains unchanged (no destructive operations)\n\n**Why This Design?**\n- Join history is tied to specific taxonomy configuration\n- Changing retriever would invalidate previous joins\n- Version tracking enables auditing and rollback"},"PathAnalysisRequest":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"Collection to analyze"},"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"Taxonomy ID"},"from_step":{"type":"string","title":"From Step","description":"Starting step"},"to_step":{"type":"string","title":"To Step","description":"Ending step"},"max_path_length":{"type":"integer","maximum":20.0,"minimum":2.0,"title":"Max Path Length","description":"Maximum number of steps in a path","default":10},"min_support":{"type":"integer","minimum":1.0,"title":"Min Support","description":"Minimum sequences required to include a path","default":5},"max_window_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Window Days","description":"Maximum duration for path completion (in days)"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Optional event filters"}},"type":"object","required":["collection_id","taxonomy_id","from_step","to_step"],"title":"PathAnalysisRequest","description":"API request model for multi-step path analysis.\n\nDiscovers the most common sequences of intermediate steps documents take\nwhen progressing from from_step to to_step.\n\nUnlike the transitions endpoint which only analyzes direct Aā†’B progressions,\nthis endpoint reveals the actual paths taken (e.g., A ā†’ X ā†’ Y ā†’ B).\n\nExample:\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\nResponse includes:\n - Most common paths sorted by frequency\n - Count and percentage for each path\n - Average duration per path"},"PathAnalysisResponse":{"properties":{"from_step":{"type":"string","title":"From Step"},"to_step":{"type":"string","title":"To Step"},"total_sequences":{"type":"integer","title":"Total Sequences","description":"Total sequences that started at from_step"},"completed_sequences":{"type":"integer","title":"Completed Sequences","description":"Number of sequences that reached to_step"},"completion_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Completion Rate","description":"Percentage that completed the path"},"paths":{"items":{"$ref":"#/components/schemas/TransitionPath"},"type":"array","maxItems":100,"title":"Paths","description":"List of paths sorted by frequency (most common first)"}},"type":"object","required":["from_step","to_step","total_sequences","completed_sequences","completion_rate","paths"],"title":"PathAnalysisResponse","description":"API response model for multi-step path analysis.\n\nContains discovered transition paths with frequency and duration statistics.\n\nExample Response:\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 ```"},"PayloadIndexConfig-Input":{"properties":{"field_name":{"type":"string","maxLength":255,"minLength":1,"title":"Field Name","description":"Name of the payload field to index. Must be unique within the namespace. Use dot notation for nested fields (e.g., 'metadata.title'). Cannot use protected system field names when is_protected=False.","examples":["metadata.title","user_id","tags"]},"type":{"$ref":"#/components/schemas/PayloadSchemaType","description":"Data type of the indexed field. Determines query capabilities and storage optimization. TEXT: Full-text search. KEYWORD: Exact matching, filtering. INTEGER/FLOAT: Range queries, sorting. DATETIME: Temporal queries. GEO: Geospatial queries. BOOL: Boolean filtering. UUID: Unique identifier matching."},"field_schema":{"anyOf":[{"$ref":"#/components/schemas/TextIndexParams"},{"$ref":"#/components/schemas/IntegerIndexParams"},{"$ref":"#/components/schemas/KeywordIndexParams"},{"$ref":"#/components/schemas/FloatIndexParams"},{"$ref":"#/components/schemas/GeoIndexParams"},{"$ref":"#/components/schemas/DatetimeIndexParams"},{"$ref":"#/components/schemas/UuidIndexParams"},{"$ref":"#/components/schemas/BoolIndexParams"},{"type":"null"}],"title":"Field Schema","description":"Optional schema configuration for the index. If not provided, uses default parameters for the specified type. Different types support different parameters (e.g., KeywordIndexParams.is_tenant)."},"is_protected":{"type":"boolean","title":"Is Protected","description":"Whether this index is system-managed and cannot be modified by users. Protected indexes (is_protected=True) are created automatically by Mixpeek and are essential for internal operations like tenant isolation, lineage tracking, and document management. Users cannot create, modify, or delete protected indexes. User-created indexes always have is_protected=False.","default":false}},"type":"object","required":["field_name","type"],"title":"PayloadIndexConfig","description":"Configuration for a payload index.\n\nDefines the structure and behavior of a payload field index in Qdrant collections.\nPayload indexes enable efficient filtering and searching on document metadata.\n\nProtected Indexes:\n System-managed indexes (is_protected=True) cannot be modified or deleted by users.\n These are essential for Mixpeek's internal operations:\n - internal_id: Tenant isolation\n - namespace_id: Namespace scoping\n - collection_id, document_id: Document lineage\n - bucket_id, object_id, root_object_id, root_bucket_id, source_object_id: Object lineage\n - created_at, updated_at: Timestamps\n\nUse Cases:\n - Create custom metadata indexes for efficient filtering\n - Configure full-text search on text fields\n - Set up geospatial queries on location data\n - Enable range queries on numeric fields\n\nRequirements:\n - field_name: REQUIRED - Must be unique within the namespace\n - type: REQUIRED - Must match PayloadSchemaType enum\n - field_schema: OPTIONAL - Auto-generated from type if not provided\n - is_protected: OPTIONAL - Defaults to False (user-managed index)","examples":[{"description":"User-created text index for full-text search","field_name":"metadata.description","is_protected":false,"type":"text"},{"description":"User-created keyword index for exact filtering","field_name":"user_id","is_protected":false,"type":"keyword"},{"description":"System-managed protected index (created automatically)","field_name":"internal_id","field_schema":{"is_tenant":true},"is_protected":true,"type":"keyword"}]},"PayloadIndexConfig-Output":{"properties":{"field_name":{"type":"string","maxLength":255,"minLength":1,"title":"Field Name","description":"Name of the payload field to index. Must be unique within the namespace. Use dot notation for nested fields (e.g., 'metadata.title'). Cannot use protected system field names when is_protected=False.","examples":["metadata.title","user_id","tags"]},"type":{"$ref":"#/components/schemas/PayloadSchemaType","description":"Data type of the indexed field. Determines query capabilities and storage optimization. TEXT: Full-text search. KEYWORD: Exact matching, filtering. INTEGER/FLOAT: Range queries, sorting. DATETIME: Temporal queries. GEO: Geospatial queries. BOOL: Boolean filtering. UUID: Unique identifier matching."},"field_schema":{"anyOf":[{"$ref":"#/components/schemas/TextIndexParams"},{"$ref":"#/components/schemas/IntegerIndexParams"},{"$ref":"#/components/schemas/KeywordIndexParams"},{"$ref":"#/components/schemas/FloatIndexParams"},{"$ref":"#/components/schemas/GeoIndexParams"},{"$ref":"#/components/schemas/DatetimeIndexParams"},{"$ref":"#/components/schemas/UuidIndexParams"},{"$ref":"#/components/schemas/BoolIndexParams"},{"type":"null"}],"title":"Field Schema","description":"Optional schema configuration for the index. If not provided, uses default parameters for the specified type. Different types support different parameters (e.g., KeywordIndexParams.is_tenant)."},"is_protected":{"type":"boolean","title":"Is Protected","description":"Whether this index is system-managed and cannot be modified by users. Protected indexes (is_protected=True) are created automatically by Mixpeek and are essential for internal operations like tenant isolation, lineage tracking, and document management. Users cannot create, modify, or delete protected indexes. User-created indexes always have is_protected=False.","default":false}},"type":"object","required":["field_name","type"],"title":"PayloadIndexConfig","description":"Configuration for a payload index.\n\nDefines the structure and behavior of a payload field index in Qdrant collections.\nPayload indexes enable efficient filtering and searching on document metadata.\n\nProtected Indexes:\n System-managed indexes (is_protected=True) cannot be modified or deleted by users.\n These are essential for Mixpeek's internal operations:\n - internal_id: Tenant isolation\n - namespace_id: Namespace scoping\n - collection_id, document_id: Document lineage\n - bucket_id, object_id, root_object_id, root_bucket_id, source_object_id: Object lineage\n - created_at, updated_at: Timestamps\n\nUse Cases:\n - Create custom metadata indexes for efficient filtering\n - Configure full-text search on text fields\n - Set up geospatial queries on location data\n - Enable range queries on numeric fields\n\nRequirements:\n - field_name: REQUIRED - Must be unique within the namespace\n - type: REQUIRED - Must match PayloadSchemaType enum\n - field_schema: OPTIONAL - Auto-generated from type if not provided\n - is_protected: OPTIONAL - Defaults to False (user-managed index)","examples":[{"description":"User-created text index for full-text search","field_name":"metadata.description","is_protected":false,"type":"text"},{"description":"User-created keyword index for exact filtering","field_name":"user_id","is_protected":false,"type":"keyword"},{"description":"System-managed protected index (created automatically)","field_name":"internal_id","field_schema":{"is_tenant":true},"is_protected":true,"type":"keyword"}]},"PayloadSchemaType":{"type":"string","enum":["keyword","integer","float","bool","geo","datetime","text","uuid"],"title":"PayloadSchemaType","description":"Payload schema type."},"PaymentMethodInfo":{"properties":{"payment_method_id":{"type":"string","title":"Payment Method Id","description":"Stripe PaymentMethod ID"},"type":{"type":"string","title":"Type","description":"Payment method type","examples":["card"]},"card_last4":{"type":"string","title":"Card Last4","description":"Last 4 digits of card","examples":["4242"]},"card_brand":{"type":"string","title":"Card Brand","description":"Card brand","examples":["visa","mastercard","amex"]}},"type":"object","required":["payment_method_id","type","card_last4","card_brand"],"title":"PaymentMethodInfo","description":"Payment method details."},"PerformanceInsight":{"properties":{"type":{"type":"string","title":"Type","description":"Insight type (bottleneck, optimization, warning)"},"severity":{"type":"string","title":"Severity","description":"Severity (info, warning, critical)"},"message":{"type":"string","title":"Message","description":"Human-readable message"},"stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage","description":"Related stage name"},"metric_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Metric Value","description":"Related metric value"},"recommendation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recommendation","description":"Recommended action"}},"type":"object","required":["type","severity","message"],"title":"PerformanceInsight","description":"Performance insight or recommendation."},"PerformanceMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket","description":"Time bucket for this metric (hour, day, etc.)"},"execution_count":{"type":"integer","title":"Execution Count","description":"Number of executions in this period"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency in milliseconds"},"p50_latency_ms":{"type":"number","title":"P50 Latency Ms","description":"50th percentile (median) latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms","description":"99th percentile latency"},"max_latency_ms":{"type":"number","title":"Max Latency Ms","description":"Maximum latency observed"}},"type":"object","required":["time_bucket","execution_count","avg_latency_ms","p50_latency_ms","p95_latency_ms","p99_latency_ms","max_latency_ms"],"title":"PerformanceMetric","description":"Single performance metric data point."},"PerformanceSummary":{"properties":{"total_executions":{"type":"integer","title":"Total Executions","description":"Total number of executions","default":0},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency","default":0.0},"p50_latency_ms":{"type":"number","title":"P50 Latency Ms","description":"Median latency","default":0.0},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency","default":0.0},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms","description":"99th percentile latency","default":0.0},"max_latency_ms":{"type":"number","title":"Max Latency Ms","description":"Maximum latency","default":0.0},"total_time_seconds":{"type":"number","title":"Total Time Seconds","description":"Total time spent across all executions","default":0.0}},"type":"object","title":"PerformanceSummary","description":"Summary statistics for performance."},"Permission":{"type":"string","enum":["read","write","delete","admin"],"title":"Permission","description":"Simplified API key permissions.\n\nThis four-value enum replaces the legacy 16-permission model. Keep usage\nsimple: prefer the least privileged option that satisfies the workflow.\n\nHierarchy (strongest -> weakest): ADMIN > DELETE > WRITE > READ."},"PipelineComparison":{"properties":{"candidate_retriever_id":{"type":"string","title":"Candidate Retriever Id","description":"ID of the candidate pipeline."},"ndcg_delta":{"additionalProperties":{"type":"number"},"type":"object","title":"Ndcg Delta","description":"Change in NDCG at each K (positive = candidate better)."},"recall_delta":{"additionalProperties":{"type":"number"},"type":"object","title":"Recall Delta","description":"Change in recall at each K (positive = candidate better)."},"latency_delta_ms":{"type":"number","title":"Latency Delta Ms","description":"Change in mean latency (positive = candidate slower)."},"p_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P Value","description":"Statistical significance of the difference (paired t-test)."},"confidence_interval":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Confidence Interval","description":"95% confidence interval for NDCG@10 delta."},"taxonomy_wins":{"items":{"type":"string"},"type":"array","title":"Taxonomy Wins","description":"Taxonomy nodes where candidate significantly outperforms."},"taxonomy_losses":{"items":{"type":"string"},"type":"array","title":"Taxonomy Losses","description":"Taxonomy nodes where candidate significantly underperforms."}},"type":"object","required":["candidate_retriever_id","ndcg_delta","recall_delta","latency_delta_ms"],"title":"PipelineComparison","description":"Statistical comparison between a candidate and baseline pipeline."},"PluginDeploymentInfo":{"properties":{"ray_cluster_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Cluster Url","description":"Ray cluster URL where plugin is deployed"},"ray_deployment_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Deployment Name","description":"Ray deployment name"},"feature_uri":{"type":"string","title":"Feature Uri","description":"Feature URI for accessing the plugin"},"deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployed At","description":"When the plugin was deployed"}},"type":"object","required":["feature_uri"],"title":"PluginDeploymentInfo","description":"Deployment information for a plugin."},"PluginListItem":{"properties":{"plugin_id":{"type":"string","title":"Plugin Id"},"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"deployed":{"type":"boolean","title":"Deployed"},"validation_status":{"type":"string","title":"Validation Status"},"feature_uri":{"type":"string","title":"Feature Uri"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["plugin_id","name","version","deployed","validation_status","feature_uri","created_at","updated_at"],"title":"PluginListItem","description":"Plugin item in list response."},"PluginRealtimeTestRequest":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Input data to pass to the inference service (e.g., {'text': 'hello'})"},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Additional parameters for the inference call"}},"type":"object","title":"PluginRealtimeTestRequest","description":"Request to test a plugin's realtime inference endpoint.\n\nUse this to debug plugin inference responses before using them in retrievers."},"PluginRealtimeTestResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Test result status: 'success' or 'error'"},"inference_name":{"type":"string","title":"Inference Name","description":"The resolved inference service name that was called"},"raw_response":{"title":"Raw Response","description":"Raw response data from the inference service"},"response_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Type","description":"Python type of the response (e.g., 'dict', 'list')"},"response_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Response Keys","description":"Top-level keys if response is a dict"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if test failed"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable status message"}},"type":"object","required":["status","inference_name"],"title":"PluginRealtimeTestResponse","description":"Response from testing a plugin's realtime inference endpoint.\n\nReturns the raw inference response so users can verify their plugin\nis returning the expected format (e.g., embedding vectors)."},"PluginStatusResponse":{"properties":{"plugin_id":{"type":"string","title":"Plugin Id","description":"Plugin identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"status":{"type":"string","title":"Status","description":"Deployment status (QUEUED, PENDING, IN_PROGRESS, DEPLOYED, FAILED, NOT_DEPLOYED)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Plugin name"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Plugin version"},"realtime_enabled":{"type":"boolean","title":"Realtime Enabled","description":"Whether realtime inference is enabled","default":false},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable status message"},"queued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Queued At","description":"When plugin was queued (ISO format)"},"estimated_completion_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Completion Seconds","description":"Estimated time to deployment completion in seconds"},"deployed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deployed","description":"Whether plugin is deployed"},"route_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Route Prefix","description":"HTTP route prefix for realtime inference"},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Feature URI for using the plugin"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At","description":"When plugin was deployed (ISO format)"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if deployment failed"}},"type":"object","required":["plugin_id","namespace_id","status"],"title":"PluginStatusResponse","description":"Response model for plugin deployment status.\n\nStatus values:\n- QUEUED: Plugin is waiting in the deployment queue\n- PENDING: Deployment triggered, waiting for Anyscale to start\n- IN_PROGRESS: Blue-green deployment in progress\n- DEPLOYED: Plugin successfully deployed and ready\n- FAILED: Deployment failed\n- NOT_DEPLOYED: Plugin not deployed for realtime inference"},"PluginUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether upload succeeded"},"plugin_id":{"type":"string","title":"Plugin Id","description":"Unique plugin identifier"},"validation_status":{"type":"string","enum":["passed","failed","pending"],"title":"Validation Status","description":"Validation status"},"validation_errors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Validation Errors","description":"Validation error messages if failed"},"deployment_status":{"type":"string","enum":["deployed","pending","failed","not_deployed"],"title":"Deployment Status","description":"Deployment status"},"feature_uri":{"type":"string","title":"Feature Uri","description":"Feature URI for the plugin"},"s3_archive_url":{"type":"string","title":"S3 Archive Url","description":"S3 URL where archive is stored"}},"type":"object","required":["success","plugin_id","validation_status","deployment_status","feature_uri","s3_archive_url"],"title":"PluginUploadResponse","description":"Response model for plugin upload."},"PostProcessingPhase":{"type":"integer","enum":[1,2,3,4],"title":"PostProcessingPhase","description":"Execution phases for post-processing applications.\n\nApplications execute in phase order (lower = earlier).\nWithin a phase, applications execute by priority (higher = earlier).\n\nPhases:\n TAXONOMY (1): Classification and labeling operations\n CLUSTER (2): Grouping and clustering operations\n ALERT (3): Notifications and alerts (default for alerts)\n RETRIEVER_ENRICHMENT (4): Retriever-based enrichment operations\n\nThe default phase for each application type:\n - TaxonomyApplicationConfig: TAXONOMY\n - ClusterApplicationConfig: CLUSTER\n - AlertApplicationConfig: ALERT\n - RetrieverEnrichmentConfig: RETRIEVER_ENRICHMENT\n\nUsers can override the phase via the `execution_phase` field to run\napplications in non-default order. For example, an alert can be configured\nto run in Phase 1 alongside taxonomies if early notification is needed.\n\nExample:\n # Default: Alert runs after taxonomies and clusters\n AlertApplicationConfig(alert_id=\"alt_123\", execution_phase=PostProcessingPhase.ALERT)\n\n # Override: Run alert early, in taxonomy phase\n AlertApplicationConfig(alert_id=\"alt_urgent\", execution_phase=PostProcessingPhase.TAXONOMY)"},"PostgreSQLConfig":{"properties":{"provider_type":{"type":"string","const":"postgresql","title":"Provider Type","default":"postgresql"},"credentials":{"$ref":"#/components/schemas/PostgreSQLCredentials","description":"REQUIRED. PostgreSQL authentication credentials. Currently supports username/password authentication."},"host":{"type":"string","title":"Host","description":"REQUIRED. PostgreSQL server hostname or IP address. Examples: 'localhost', 'db.example.com', '192.168.1.100'","examples":["localhost","db.example.com","192.168.1.100"]},"port":{"type":"integer","maximum":65535.0,"minimum":1.0,"title":"Port","description":"PostgreSQL server port. Default: 5432 (standard PostgreSQL port)","default":5432},"database":{"type":"string","title":"Database","description":"REQUIRED. Database name to connect to. User must have CONNECT privilege on this database.","examples":["production","analytics","customer_data"]},"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema","description":"Schema name for default context. Default: 'public'. User must have USAGE privilege on this schema.","default":"public","examples":["public","raw_data","transformed"]},"ssl_mode":{"type":"string","title":"Ssl Mode","description":"SSL/TLS connection mode. Options: 'disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full'. Default: 'prefer'. RECOMMENDED: Use 'require' or stricter for production environments.","default":"prefer","examples":["disable","prefer","require","verify-full"]},"incremental_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incremental Column","description":"NOT REQUIRED. Column name for incremental sync watermark. Should be a TIMESTAMP or DATE column that tracks row modifications. Common values: updated_at, modified_at, last_updated. If omitted, full table scan on every sync.","examples":["updated_at","modified_at","last_updated"]},"primary_key_columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Primary Key Columns","description":"NOT REQUIRED. Column names forming the primary key for stable object IDs. Used to generate deterministic file_id for deduplication. If omitted, uses hash of entire row content.","examples":[["id"],["user_id","timestamp"],["customer_id","order_id"]]},"query_timeout_seconds":{"type":"integer","maximum":3600.0,"minimum":1.0,"title":"Query Timeout Seconds","description":"Query timeout in seconds. Default: 300 seconds (5 minutes). Increase for large tables or complex queries.","default":300},"fetch_size":{"type":"integer","maximum":10000.0,"minimum":100.0,"title":"Fetch Size","description":"Number of rows to fetch per batch. Higher values reduce network overhead but increase memory usage. Default: 1000 rows.","default":1000}},"type":"object","required":["credentials","host","database"],"title":"PostgreSQLConfig","description":"PostgreSQL database configuration for table-based sync and SQL queries.\n\nEnables syncing PostgreSQL table rows as JSON objects and running SQL queries\nvia the SQL Lookup retriever stage. Each row becomes one object, with\nincremental sync via watermark columns.\n\nAuthentication:\n - Username/Password: Standard PostgreSQL authentication\n\nRequirements:\n - PostgreSQL 12+ recommended\n - Read access to target tables\n - Network connectivity to PostgreSQL server\n\nUse Cases:\n - Sync customer data tables for AI/ML pipelines\n - Run SQL lookups to enrich documents in retriever pipelines\n - Ingest product catalog for search/recommendations\n - Process transaction logs for analytics\n\nExample:\n ```python\n config = {\n \"provider_type\": \"postgresql\",\n \"credentials\": {\n \"type\": \"username_password\",\n \"username\": \"mixpeek_sync\",\n \"password\": \"secure_password\",\n },\n \"host\": \"db.example.com\",\n \"port\": 5432,\n \"database\": \"production\",\n \"schema\": \"public\",\n \"ssl_mode\": \"require\",\n }\n ```","examples":[{"credentials":{"password":"dev_password","type":"username_password","username":"mixpeek_user"},"database":"mixpeek_test","description":"Local PostgreSQL development setup","host":"localhost","port":5432,"provider_type":"postgresql","schema":"public","ssl_mode":"disable"},{"credentials":{"password":"secure_password_here","type":"username_password","username":"mixpeek_sync"},"database":"production","description":"Production PostgreSQL with SSL and incremental sync","host":"db.example.com","incremental_column":"updated_at","port":5432,"primary_key_columns":["id"],"provider_type":"postgresql","schema":"public","ssl_mode":"require"}]},"PostgreSQLCredentials":{"properties":{"type":{"type":"string","const":"username_password","title":"Type","default":"username_password"},"username":{"type":"string","title":"Username","description":"REQUIRED. PostgreSQL username for authentication.","examples":["mixpeek_sync","readonly_user"]},"password":{"type":"string","title":"Password","description":"REQUIRED. PostgreSQL password for authentication. SECURITY: This field is encrypted at rest via CSFLE. Never log or expose."}},"type":"object","required":["username","password"],"title":"PostgreSQLCredentials","description":"PostgreSQL username/password authentication.\n\nStandard username/password authentication for PostgreSQL databases.\nPassword is encrypted at rest using MongoDB CSFLE.\n\nSecurity:\n - password field is encrypted at rest via CSFLE\n - Consider using SSL mode 'require' for production\n - Use dedicated read-only database user for sync operations"},"PredictorLift":{"properties":{"field":{"type":"string","title":"Field","description":"Covariate field name"},"value":{"type":"string","title":"Value","description":"Specific value or bin label"},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Number of sequences with this value"},"conversion_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Conversion Rate","description":"Conversion rate for this value"},"lift":{"type":"number","title":"Lift","description":"Lift relative to baseline (>1.0 = positive, <1.0 = negative)"}},"type":"object","required":["field","value","count","conversion_rate","lift"],"title":"PredictorLift","description":"Lift calculation for a specific covariate value.\n\nLift measures how much a specific value increases/decreases conversion likelihood\ncompared to the baseline. Lift > 1.0 means the value helps conversion.\n\nAttributes:\n field: Name of the covariate (e.g., \"Sender Domain\", \"Word Count Q3\")\n value: Specific value or bin (e.g., \"gmail.com\", \"Q3\")\n count: Number of sequences with this value\n conversion_rate: Conversion rate for this value (0.0 to 1.0)\n lift: Conversion rate / baseline rate (1.0 = no effect, >1.0 = positive, <1.0 = negative)\n\nExample:\n ```python\n # Sender domain \"enterprise.com\" has 2.5x baseline conversion\n PredictorLift(\n field=\"Sender Domain\",\n value=\"enterprise.com\",\n count=150,\n conversion_rate=0.75, # 75% conversion\n lift=2.5 # 2.5x the baseline rate\n )\n ```\n\nInterpretation:\n - lift = 1.5: This value increases conversion by 50%\n - lift = 1.0: No effect on conversion\n - lift = 0.5: This value decreases conversion by 50%"},"PublicInteractionBatchRequest":{"properties":{"interactions":{"items":{"$ref":"#/components/schemas/PublicInteractionRequest"},"type":"array","maxItems":100,"minItems":1,"title":"Interactions","description":"List of interactions to track (max 100 per batch)"}},"type":"object","required":["interactions"],"title":"PublicInteractionBatchRequest","description":"Request to track multiple interactions in batch."},"PublicInteractionRequest":{"properties":{"document_id":{"type":"string","title":"Document Id","description":"ID of the document that was interacted with (from search results)","examples":["doc_abc123","prod_xyz789"]},"interaction_type":{"items":{"$ref":"#/components/schemas/InteractionType"},"type":"array","minItems":1,"title":"Interaction Type","description":"Type(s) of interaction that occurred","examples":[["click"],["view","click"],["positive_feedback"]]},"position":{"type":"integer","minimum":0.0,"title":"Position","description":"Position in search results (0-indexed)","examples":[0,1,5,15]},"execution_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Id","description":"ID of the retriever execution that generated these results. HIGHLY RECOMMENDED for analytics.","examples":["exec_abc123xyz"]},"query_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Query Snapshot","description":"Snapshot of the query that generated these results. HIGHLY RECOMMENDED for training optimization.","examples":[{"text":"wireless headphones"},{"filters":{"price":{"lte":1000}},"text":"laptop"}]},"document_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Document Score","description":"Initial retrieval score of this document","examples":[0.95,0.87,0.62]},"result_set_size":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Result Set Size","description":"Total number of results shown","examples":[10,20,50]},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session identifier for tracking user journey","examples":["sess_abc123"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional context about the interaction"}},"type":"object","required":["document_id","interaction_type","position"],"title":"PublicInteractionRequest","description":"Request to track a single interaction from public retriever.\n\nSimplified wrapper around SearchInteraction for public API use."},"PublicNameAvailabilityResponse":{"properties":{"name":{"type":"string","title":"Name","description":"The public name that was checked"},"available":{"type":"boolean","title":"Available","description":"Whether the name is available for use"}},"type":"object","required":["name","available"],"title":"PublicNameAvailabilityResponse","description":"Response for public name availability check."},"PublicPageConfigResponse":{"properties":{"slug":{"type":"string","title":"Slug"},"template":{"type":"string","title":"Template"},"sections":{"items":{"$ref":"#/components/schemas/SectionConfig"},"type":"array","title":"Sections"},"custom_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Html"},"meta":{"$ref":"#/components/schemas/PageMeta"},"hero":{"anyOf":[{"$ref":"#/components/schemas/HeroConfig"},{"type":"null"}]},"theme":{"$ref":"#/components/schemas/ThemeConfig"},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}]},"stats":{"items":{"$ref":"#/components/schemas/StatItem"},"type":"array","title":"Stats"},"featured_gallery":{"anyOf":[{"$ref":"#/components/schemas/FeaturedGalleryConfig-Output"},{"type":"null"}]},"tabs":{"items":{"$ref":"#/components/schemas/PageTab-Output"},"type":"array","title":"Tabs"},"is_active":{"type":"boolean","title":"Is Active"},"password_protected":{"type":"boolean","title":"Password Protected"}},"type":"object","required":["slug","template","meta","hero","theme","seo","stats","featured_gallery","tabs","is_active","password_protected"],"title":"PublicPageConfigResponse","description":"Public page configuration (strips internal fields)."},"PublicPageSearchRequest":{"properties":{"tab_id":{"type":"string","title":"Tab Id","description":"Tab ID to search within"},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Search inputs"},"settings":{"additionalProperties":true,"type":"object","title":"Settings","description":"Optional execution settings"}},"additionalProperties":true,"type":"object","required":["tab_id"],"title":"PublicPageSearchRequest","description":"Request to execute a search on a specific tab of a Page.\n\nExtra top-level fields (e.g. ``query_image``, ``query_text``) are automatically\nmerged into ``inputs`` so callers can pass retriever inputs at the top level\nwithout nesting them inside an ``inputs`` key."},"PublicRetrieverConfigResponse":{"properties":{"public_name":{"type":"string","title":"Public Name","description":"Public name of the retriever"},"public_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Api Key","description":"DEPRECATED: API keys are no longer required for public access. The execute endpoint can be called without authentication."},"display_config":{"$ref":"#/components/schemas/DisplayConfig-Output","description":"Display configuration for rendering the UI. Includes inputs, theme, layout, and exposed fields."},"password_protected":{"type":"boolean","title":"Password Protected","description":"Whether this retriever requires password authentication"},"retriever_metadata":{"anyOf":[{"$ref":"#/components/schemas/RetrieverMetadata"},{"type":"null"}],"description":"OPTIONAL. Technical metadata about how the retriever works. Only present if include_metadata=True was set during publishing."}},"type":"object","required":["public_name","display_config","password_protected"],"title":"PublicRetrieverConfigResponse","description":"Response for fetching public retriever configuration (for UI rendering).\n\nThis is what the public frontend (mxp.co/r/{name}) fetches to render\nthe search interface. It includes everything needed for UI rendering.\n\nNote: API keys are no longer required. The execute endpoint can be called\nwithout authentication - rate limiting and optional password protection\nprovide security."},"PublicRetrieverListItem":{"properties":{"public_name":{"type":"string","title":"Public Name","description":"Public URL-safe name used in the public URL"},"public_url":{"type":"string","title":"Public Url","description":"Full public URL to the retriever page","examples":["https://mxp.co/r/video-search"]},"title":{"type":"string","title":"Title","description":"Display title from display_config","examples":["Video Search","Product Catalog"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Display description from display_config"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"Logo URL from display_config"},"icon_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon from display_config"},"og_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Og Image Url","description":"Social preview/OG image URL from display_config"},"password_protected":{"type":"boolean","title":"Password Protected","description":"Whether password authentication is required"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the retriever is active"},"external_links":{"items":{"$ref":"#/components/schemas/ExternalLink"},"type":"array","title":"External Links","description":"External resource links (GitHub, blog posts, docs, etc.)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the retriever was published"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the retriever was last updated"}},"type":"object","required":["public_name","public_url","title","password_protected","is_active","created_at","updated_at"],"title":"PublicRetrieverListItem","description":"Simplified retriever information for public listing.\n\nProvides essential details for browsing public retrievers without\nexposing sensitive configuration or credentials."},"PublicRetrieverListStats":{"properties":{"total_active":{"type":"integer","title":"Total Active","description":"Number of active public retrievers","default":0},"total_password_protected":{"type":"integer","title":"Total Password Protected","description":"Number of password-protected retrievers","default":0},"total_open":{"type":"integer","title":"Total Open","description":"Number of fully open (no password) retrievers","default":0}},"type":"object","title":"PublicRetrieverListStats","description":"Aggregate statistics for public retrievers list."},"PublicRetrieverTemplateResponse":{"properties":{"retriever_name":{"type":"string","title":"Retriever Name","description":"Original retriever name (you'll change this when creating your own). Provided as reference.","examples":["video-search-example","product-catalog-demo"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Original retriever description (you can use or modify this). Provides context about what this retriever does."},"collection_identifiers":{"items":{"type":"string"},"type":"array","title":"Collection Identifiers","description":"IMPORTANT: These are the original collections. You MUST replace these with your own collection identifiers when creating a retriever from this template.","examples":[["public_videos"],["demo_products","demo_images"]]},"stages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Stages","description":"Pipeline stages configuration. You can use as-is or modify for your needs. This is the core retrieval logic."},"input_schema":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Output"},"type":"object","title":"Input Schema","description":"Input schema defining expected inputs. If you change the input field names, make sure to update references in stages (e.g., {{inputs.query}})."},"budget_limits":{"additionalProperties":true,"type":"object","title":"Budget Limits","description":"Budget limits for execution. You can adjust these based on your needs."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Original tags (optional, for reference)"},"display_config":{"anyOf":[{"$ref":"#/components/schemas/DisplayConfig-Output"},{"type":"null"}],"description":"OPTIONAL: Display configuration used for the public interface. Include this if you plan to publish your retriever and want to use a similar UI design. Otherwise, you can omit it."},"source_public_name":{"type":"string","title":"Source Public Name","description":"Public name of the source retriever (for reference)","examples":["video-search","product-catalog"]},"source_public_url":{"type":"string","title":"Source Public Url","description":"Public URL of the source retriever (to view it in action)","examples":["https://mxp.co/r/video-search"]},"feature_extractors":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Feature Extractors","description":"Feature extractors from all collections used by this retriever. Each extractor includes: feature_extractor_name, version, params, input_mappings, collection_id, and collection_name for reference. Shows how each collection processes data into searchable features."}},"type":"object","required":["retriever_name","collection_identifiers","stages","input_schema","budget_limits","source_public_name","source_public_url"],"title":"PublicRetrieverTemplateResponse","description":"Response containing public retriever configuration as a reusable template.\n\nThis returns the retriever's configuration in a format that can be directly\nused in a CreateRetrieverRequest. Users can copy this config, modify it for\ntheir needs (e.g., change collection_identifiers), and create their own retriever.\n\nUse Case:\n 1. Browse public retrievers to find patterns you like\n 2. GET /public/retrievers/{public_name}/template to get the config\n 3. Modify collection_identifiers and other fields as needed\n 4. POST /retrievers to create your own retriever with this config\n 5. Optionally POST /retrievers/{id}/publish to publish it similarly","examples":[{"budget_limits":{"max_credits":10.0,"max_time_ms":30000},"collection_identifiers":["demo_videos"],"description":"AI-powered video search using semantic understanding","display_config":{"components":{"result_layout":"grid","show_search":true},"description":"Search through video content","exposed_fields":["title","thumbnail_url","duration"],"inputs":[{"field_name":"query","field_schema":{"type":"text"},"label":"Search Videos","order":0,"placeholder":"Describe what you're looking for...","required":true}],"title":"Video Search"},"input_schema":{"query":{"description":"Search query","examples":["action scenes","romantic moments"],"required":true,"type":"text"}},"retriever_name":"video-search-demo","source_public_name":"video-search","source_public_url":"https://mxp.co/r/video-search","stages":[{"config":{"parameters":{"final_top_k":25,"searches":[{"feature_uri":"mixpeek://text_extractor@v1/embedding","query":{"input_mode":"text","text":"{{inputs.query}}"},"top_k":100}]},"stage_id":"feature_search"},"stage_name":"semantic_search","stage_type":"filter"}],"tags":["video","semantic-search","demo"]}]},"PublishRetrieverRequest":{"properties":{"display_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Display Name","description":"Human-readable display name for this retriever (free-form text). Example: 'Peptide Evidence Search'. A URL-safe slug is auto-generated from this if `public_name` is not provided.","examples":["Peptide Evidence Search","Product Catalog","Video Library"]},"public_name":{"anyOf":[{"type":"string","maxLength":50,"minLength":3,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},{"type":"null"}],"title":"Public Name","description":"URL-safe slug (lowercase letters, digits, hyphens only). Must start and end with an alphanumeric character. Example: 'peptide-evidence-search'. Used in the public URL: mxp.co/r/{public_name}. Auto-generated from `display_name` if not provided.","examples":["video-search","product-catalog","creative-assets"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Description of this public retriever. Explains what the retriever does and what it searches. Displayed in public listings and search results.","examples":["AI-powered video search using semantic understanding","Search through product catalog with visual similarity"]},"icon_base64":{"anyOf":[{"type":"string","maxLength":300000},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon for this public retriever. Data URI format recommended. Max size: ~200KB encoded. Displayed in public listings and as the retriever's icon.","examples":["data:image/png;base64,iVBORw0KGgoAAAANS..."]},"display_config":{"anyOf":[{"$ref":"#/components/schemas/DisplayConfig-Input"},{"type":"null"}],"description":"Display configuration defining how the public UI should be rendered. Includes input fields, theme, layout, and exposed result fields. If not provided, uses the retriever's stored display_config."},"rate_limit_config":{"$ref":"#/components/schemas/RateLimitConfig","description":"Rate limiting configuration for public endpoint. Defaults to STANDARD tier (10/min, 100/hour, 1k/day). Use ELEVATED tier for trusted public apps (30/min, 500/hour, 5k/day). Use ENTERPRISE tier for monitored deployments (100/min, 2k/hour, 20k/day). Custom limits override tier defaults."},"password_secret_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password Secret Name","description":"OPTIONAL. Name of organization secret containing password for access protection. If provided, users must send password via X-Retriever-Password header.","examples":["published_retriever_password","demo_password"]},"include_metadata":{"type":"boolean","title":"Include Metadata","description":"Whether to capture and store retriever metadata (stages, collections, capabilities). Recommended: True for better developer experience and debugging. Default: True.","default":true},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for categorizing this retriever. Used for filtering in public listings and gallery views.","examples":[["sandbox","demo","video"],["marketplace","adtech"]]},"category":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Category","description":"Primary category for this retriever. Examples: 'sandbox', 'marketplace', 'demo', 'production'.","examples":["sandbox","marketplace"]}},"type":"object","title":"PublishRetrieverRequest","description":"Request to publish a retriever.\n\nEither `public_name` (slug) or `display_name` (human-readable) is required.\nIf only `display_name` is provided, a slug is auto-generated from it.\nIf `display_config` is not provided, the retriever's stored display_config will be used."},"PublishRetrieverResponse":{"properties":{"public_id":{"type":"string","title":"Public Id","description":"Public identifier for this published retriever"},"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the underlying retriever"},"public_url":{"type":"string","title":"Public Url","description":"Full public URL to the retriever page","examples":["https://mxp.co/r/video-search"]},"short_url":{"type":"string","title":"Short Url","description":"Short URL via mxp.co redirect (same as public_url)","examples":["https://mxp.co/r/video-search"]},"public_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Api Key","description":"DEPRECATED: API keys are no longer required for public retriever access. For programmatic SDK access, create a ret_sk_ key via the retrievers/{id}/keys endpoint."}},"type":"object","required":["public_id","retriever_id","public_url","short_url"],"title":"PublishRetrieverResponse","description":"Response after successfully publishing a retriever."},"PublishedRetrieverResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the underlying retriever"},"public_id":{"type":"string","title":"Public Id","description":"Public identifier for this published retriever"},"public_name":{"type":"string","title":"Public Name","description":"Public URL-safe name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of this public retriever"},"icon_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Base64","description":"Base64 encoded icon/favicon for this retriever"},"public_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Api Key","description":"DEPRECATED: Public API key (prk_). API keys are no longer required for public retriever access. For SDK access, use ret_sk_ keys."},"display_config":{"$ref":"#/components/schemas/DisplayConfig-Output","description":"Display configuration for UI rendering"},"rate_limit_config":{"$ref":"#/components/schemas/RateLimitConfig","description":"Rate limiting configuration"},"password_protected":{"type":"boolean","title":"Password Protected","description":"Whether password protection is enabled"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the published retriever is active"},"retriever_metadata":{"anyOf":[{"$ref":"#/components/schemas/RetrieverMetadata"},{"type":"null"}],"description":"Optional technical metadata about the retriever"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for categorizing this retriever"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Primary category for this retriever"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when published"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Timestamp when last updated"}},"type":"object","required":["retriever_id","public_id","public_name","display_config","rate_limit_config","password_protected","is_active","created_at","updated_at"],"title":"PublishedRetrieverResponse","description":"Response model for GET published retriever.\n\nReturns the full published retriever config including the public API key\nsince the user already has access to it."},"RSSConfig":{"properties":{"provider_type":{"type":"string","const":"rss","title":"Provider Type","default":"rss"},"credentials":{"anyOf":[{"$ref":"#/components/schemas/RSSHttpHeaderCredentials"},{"type":"null"}],"description":"Optional HTTP headers for private feeds."},"user_agent":{"type":"string","title":"User Agent","description":"User-Agent header for feed requests.","default":"Mixpeek RSS Sync/1.0"},"request_timeout":{"type":"integer","maximum":120.0,"minimum":5.0,"title":"Request Timeout","description":"HTTP request timeout in seconds.","default":30}},"type":"object","title":"RSSConfig","description":"RSS/Atom feed configuration. source_path = feed URL.","examples":[{"description":"Public RSS feed","provider_type":"rss","request_timeout":30,"user_agent":"Mixpeek RSS Sync/1.0"},{"credentials":{"headers":{"Authorization":"Bearer your-token-here"},"type":"http_headers"},"description":"Private RSS feed with auth header","provider_type":"rss","request_timeout":30,"user_agent":"Mixpeek RSS Sync/1.0"}]},"RSSFieldSource":{"properties":{"type":{"type":"string","const":"rss_field","title":"Type","description":"Source type identifier.","default":"rss_field"},"field":{"type":"string","title":"Field","description":"RSS entry field: title, author, link, categories, summary, published"}},"type":"object","required":["field"],"title":"RSSFieldSource","description":"Extract value from an RSS entry field.\n\nProvider Compatibility: RSS only\n\nAvailable fields: title, author, link, categories, summary, published\n\nExample mapping:\n {\"type\": \"rss_field\", \"field\": \"title\"} -> extracts entry title\n {\"type\": \"rss_field\", \"field\": \"categories\"} -> extracts list of category terms\n\nAttributes:\n type: Must be \"rss_field\" to identify this source type\n field: RSS entry field name to extract"},"RSSHttpHeaderCredentials":{"properties":{"type":{"type":"string","const":"http_headers","title":"Type","default":"http_headers"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"HTTP headers for feed requests (e.g., Authorization)."}},"type":"object","title":"RSSHttpHeaderCredentials","description":"Optional HTTP credentials for private RSS feeds."},"RangeBucket":{"properties":{"field":{"type":"string","title":"Field","description":"Numeric field to create buckets for. REQUIRED, must be a numeric field. Supports dot notation for nested fields. Values will be grouped into ranges defined by boundaries.","examples":["metadata.duration","metadata.views","metadata.file_size"]},"boundaries":{"items":{"anyOf":[{"type":"integer"},{"type":"number"}]},"type":"array","minItems":1,"title":"Boundaries","description":"List of boundary values defining bucket ranges. REQUIRED, must be sorted in ascending order. Creates N+1 buckets for N boundaries: [0, 10, 20] creates: <0, 0-10, 10-20, >20. Values on boundaries go into the lower bucket.","examples":[[0,60,300,600],[0,100,1000,10000]]},"default_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Bucket","description":"Name for values outside defined boundaries. OPTIONAL, defaults to 'other'. Used for values below min or above max boundary.","examples":["other","outliers","unknown"]}},"type":"object","required":["field","boundaries"],"title":"RangeBucket","description":"Configuration for range-based bucketing.\n\nGroups numeric values into ranges/buckets for histogram-style analysis.\n\nRequirements:\n - field: REQUIRED, numeric field to bucket\n - boundaries: REQUIRED, list of boundary values defining buckets\n - default_bucket: OPTIONAL, name for values outside boundaries\n\nExamples:\n - Video duration buckets: [0, 60, 300, 600] creates: 0-60s, 60-300s, 300-600s, 600+s\n - View count buckets: [0, 100, 1000, 10000] creates: 0-100, 100-1K, 1K-10K, 10K+ views","examples":[{"boundaries":[0,60,300,600],"default_bucket":"over_600s","description":"Duration buckets (0-60s, 60-300s, 300-600s, 600+s)","field":"metadata.duration"},{"boundaries":[0,100,1000,10000],"default_bucket":"viral","description":"View count buckets","field":"metadata.views"}]},"RateLimitConfig":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Enable rate limiting for this published retriever. Set to False to disable all rate limiting (not recommended for public retrievers).","default":true},"tier":{"$ref":"#/components/schemas/RateLimitTier","description":"Rate limit tier preset. STANDARD (default): 60/min, 1k/hour, 10k/day. ELEVATED: 300/min, 10k/hour, 100k/day. ENTERPRISE: 1000/min, 50k/hour, 500k/day. UNLIMITED: No limits. Custom limits override tier defaults.","default":"standard","examples":["standard","elevated","enterprise"]},"requests_per_minute":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Requests Per Minute","description":"Maximum requests per minute (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default."},"requests_per_hour":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Requests Per Hour","description":"Maximum requests per hour (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default."},"requests_per_day":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Requests Per Day","description":"Maximum requests per day (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default."},"max_results_per_query":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Max Results Per Query","description":"Maximum number of results per search query (1-1000)","default":100},"enable_ip_limits":{"type":"boolean","title":"Enable Ip Limits","description":"Enable IP-based rate limiting in addition to retriever-level limits. Useful for preventing individual IPs from monopolizing the retriever.","default":false},"max_requests_per_ip_hour":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Requests Per Ip Hour","description":"Maximum requests per IP address per hour (OPTIONAL). Only enforced if enable_ip_limits=True. Recommended: 100-500 for standard tier, 1000+ for elevated/enterprise."}},"type":"object","title":"RateLimitConfig","description":"Rate limiting configuration for public retriever API.\n\nControls how many requests can be made to the public endpoint\nto prevent abuse and manage infrastructure costs.\n\nYou can either use a preset tier or specify custom limits.\nIf both tier and custom limits are provided, custom limits override the tier defaults.","examples":[{"description":"Standard tier (default) - 10/min, 100/hour, 1k/day","enabled":true,"max_results_per_query":50,"tier":"standard"},{"description":"Elevated tier - 30/min, 500/hour, 5k/day","enable_ip_limits":true,"enabled":true,"max_requests_per_ip_hour":100,"max_results_per_query":100,"tier":"elevated"},{"description":"Enterprise tier - 100/min, 2k/hour, 20k/day","enable_ip_limits":true,"enabled":true,"max_requests_per_ip_hour":500,"max_results_per_query":200,"tier":"enterprise"},{"description":"Custom limits overriding standard tier","enabled":true,"max_results_per_query":100,"requests_per_hour":200,"requests_per_minute":20,"tier":"standard"}]},"RateLimitTier":{"type":"string","enum":["standard","elevated","enterprise","unlimited"],"title":"RateLimitTier","description":"Rate limit tier for public retrievers.\n\nDefines preset rate limit configurations for different use cases.\n\nTiers:\n STANDARD: Default tier for most public retrievers\n - 10 requests/minute\n - 100 requests/hour\n - 1,000 requests/day\n - Suitable for demos, prototypes, and low-traffic public applications\n\n ELEVATED: Higher limits for trusted public applications\n - 30 requests/minute (3x standard)\n - 500 requests/hour (5x standard)\n - 5,000 requests/day (5x standard)\n - Suitable for production public apps with moderate traffic\n\n ENTERPRISE: High limits for enterprise public deployments\n - 100 requests/minute (10x standard)\n - 2,000 requests/hour (20x standard)\n - 20,000 requests/day (20x standard)\n - Suitable for high-traffic public applications with monitoring\n\n UNLIMITED: No rate limiting\n - Use with extreme caution - only for fully trusted deployments\n - Still respects max_results_per_query and IP limits if enabled"},"RawInferenceRequest":{"properties":{"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"Provider name: openai, google, anthropic (required if inference_name not set)","examples":["openai","google","anthropic"]},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model identifier specific to the provider (required if inference_name not set)","examples":["gpt-4o-mini","gemini-1.5-flash","claude-3-5-sonnet","text-embedding-3-large","whisper-1"]},"inference_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Name","description":"Custom plugin inference name (alternative to provider+model)","examples":["my_text_embedder_1_0_0","custom_reranker_2_0_0"]},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Feature URI to resolve to inference_name (alternative to inference_name). Format: mixpeek://{extractor}@{version}/{vector_index_name}","examples":["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1","mixpeek://my_custom_embedder@1.0.0/embedding"]},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Model-specific inputs. Chat: {prompts: [str]}, Embeddings: {text: str} or {texts: [str]}, Transcription: {audio_url: str}, Vision: {prompts: [str], image_url: str}","examples":[{"prompts":["What is the capital of France?"]},{"text":"machine learning"},{"audio_url":"https://example.com/audio.mp3"}]},"parameters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameters","description":"Optional parameters for inference. Common: temperature (float), max_tokens (int), schema (dict for structured output)","examples":[{"max_tokens":500,"temperature":0.7}]},"enable_semantic_cache":{"type":"boolean","title":"Enable Semantic Cache","description":"Enable semantic caching (vCache) for LLM chat operations. When enabled, semantically similar prompts may return cached responses, reducing latency and cost. Only applies to chat/completion models.","default":false},"cache_delta":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Cache Delta","description":"Maximum error rate for semantic cache (0.0-1.0). Lower values are more conservative. Default uses system setting (0.02 = 2%)."}},"type":"object","required":["inputs"],"title":"RawInferenceRequest","description":"Request for raw inference without retriever framework.\n\nThis endpoint provides direct access to inference services with minimal configuration.\nIdeal for simple LLM calls, embeddings, transcription, or vision tasks without\nrequiring collection setup or retriever configuration.\n\nYou can either use:\n- `provider` + `model` for standard providers (openai, google, anthropic)\n- `inference_name` for custom plugins\n\nExamples:\n # Chat completion (provider + model)\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 # Text embedding (provider + model)\n {\n \"provider\": \"openai\",\n \"model\": \"text-embedding-3-large\",\n \"inputs\": {\"text\": \"machine learning\"},\n \"parameters\": {}\n }\n\n # Custom plugin (inference_name)\n {\n \"inference_name\": \"my_text_embedder_1_0_0\",\n \"inputs\": {\"text\": \"hello world\"},\n \"parameters\": {}\n }\n\n # Audio transcription\n {\n \"provider\": \"openai\",\n \"model\": \"whisper-1\",\n \"inputs\": {\"audio_url\": \"https://example.com/audio.mp3\"},\n \"parameters\": {}\n }\n\n # Vision (multimodal)\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 }"},"RawInferenceResponse":{"properties":{"data":{"title":"Data","description":"Inference results (structure varies by modality)"},"provider":{"type":"string","title":"Provider","description":"Provider that was used"},"model":{"type":"string","title":"Model","description":"Model that was used"},"tokens_used":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Tokens Used","description":"Token usage statistics (if available)","examples":[{"completion":120,"prompt":15,"total":135}]},"latency_ms":{"type":"number","title":"Latency Ms","description":"Total inference latency in milliseconds"},"cached":{"type":"boolean","title":"Cached","description":"Whether the response was served from semantic cache (vCache)","default":false}},"type":"object","required":["data","provider","model","latency_ms"],"title":"RawInferenceResponse","description":"Response from raw inference.\n\nReturns the inference results along with metadata about the request."},"ReconfigureNamespaceRequest":{"properties":{"confirm":{"type":"boolean","title":"Confirm","description":"Must be True to confirm this destructive operation. Existing Qdrant data will be deleted and must be re-ingested."}},"type":"object","required":["confirm"],"title":"ReconfigureNamespaceRequest","description":"Request to reconfigure a namespace's Qdrant collection schema.\n\nThis is a destructive operation: it deletes and recreates the Qdrant collection\nwith merged vector definitions from all deployed plugins. Existing data is lost\nand must be re-ingested by triggering batches on each collection."},"ReconfigureNamespaceResponse":{"properties":{"namespace_id":{"type":"string","title":"Namespace Id","description":"The reconfigured namespace"},"status":{"type":"string","title":"Status","description":"Operation status: 'reconfigured' or 'no_changes_needed'"},"previous_points_count":{"type":"integer","title":"Previous Points Count","description":"Number of Qdrant points that were in the collection before reconfigure"},"vectors_added":{"items":{"type":"string"},"type":"array","title":"Vectors Added","description":"Names of new vector indexes added to the schema"},"vectors_total":{"items":{"type":"string"},"type":"array","title":"Vectors Total","description":"All vector index names in the reconfigured collection"},"collections_to_reprocess":{"items":{"type":"string"},"type":"array","title":"Collections To Reprocess","description":"Collection IDs that need to be re-triggered to populate new vectors"},"message":{"type":"string","title":"Message","description":"Human-readable status message"}},"type":"object","required":["namespace_id","status","previous_points_count","vectors_added","vectors_total","collections_to_reprocess","message"],"title":"ReconfigureNamespaceResponse","description":"Response from reconfiguring a namespace's Qdrant collection."},"ReminderPreferences":{"properties":{"enabled":{"type":"boolean","title":"Enabled","description":"Master toggle for all reminder emails","default":true},"onboarding_nudges":{"type":"boolean","title":"Onboarding Nudges","description":"Funnel progression nudges","default":true},"engagement_reminders":{"type":"boolean","title":"Engagement Reminders","description":"Re-engagement emails for inactivity","default":true},"feature_tips":{"type":"boolean","title":"Feature Tips","description":"Helpful tips and inspiration","default":true},"quiet_hours_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quiet Hours Start","description":"Hour (0-23) to start quiet period (UTC)"},"quiet_hours_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quiet Hours End","description":"Hour (0-23) to end quiet period (UTC)"}},"type":"object","title":"ReminderPreferences","description":"User preferences for reminder/nudge emails."},"ReminderPreferencesResponse":{"properties":{"reminders":{"$ref":"#/components/schemas/ReminderPreferences","description":"Reminder/nudge email preferences"}},"type":"object","required":["reminders"],"title":"ReminderPreferencesResponse","description":"Response model for reminder preferences."},"RenderStrategy":{"type":"string","enum":["static","javascript","auto"],"title":"RenderStrategy","description":"Strategy for rendering web pages.\n\nValues:\n STATIC: Fast HTTP fetch, works for most sites\n JAVASCRIPT: Browser rendering via Playwright for SPAs\n AUTO: Try static first, fall back to JS if content too short"},"ResourceFilter":{"properties":{"collection_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Collection Ids","description":"Specific collection IDs to migrate"},"taxonomy_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Taxonomy Ids","description":"Specific taxonomy IDs to migrate"},"cluster_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Cluster Ids","description":"Specific cluster IDs to migrate"},"retriever_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Retriever Ids","description":"Specific retriever IDs to migrate"},"date_range":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Date Range","description":"Date range filter (after, before)"},"auto_include_dependencies":{"type":"boolean","title":"Auto Include Dependencies","description":"Automatically include required dependencies","default":true}},"type":"object","title":"ResourceFilter","description":"Filters for selective resource migration."},"ResourceProgress":{"properties":{"resource_id":{"type":"string","title":"Resource Id","description":"Resource ID"},"resource_type":{"$ref":"#/components/schemas/shared__namespaces__migrations__models__ResourceType","description":"Resource type"},"status":{"$ref":"#/components/schemas/MigrationStatus","description":"Resource status"},"progress_percent":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Progress Percent","description":"Progress %","default":0.0},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error if failed"}},"type":"object","required":["resource_id","resource_type","status"],"title":"ResourceProgress","description":"Progress tracking for individual resources."},"ResourceResult":{"properties":{"resource_type":{"type":"string","title":"Resource Type","description":"Type of resource (namespace, bucket, etc.)"},"name":{"type":"string","title":"Name","description":"Resource name from manifest"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"Created resource ID"},"status":{"$ref":"#/components/schemas/ResourceResultStatus","description":"Result status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"}},"type":"object","required":["resource_type","name","status"],"title":"ResourceResult","description":"Result of applying a single resource.","examples":[{"name":"video_search","resource_id":"ns_abc123","resource_type":"namespace","status":"created"}]},"ResourceResultStatus":{"type":"string","enum":["created","skipped","failed"],"title":"ResourceResultStatus","description":"Status of a resource creation attempt."},"ResourceScope-Input":{"properties":{"resource_type":{"$ref":"#/components/schemas/ResourceType-Input","description":"Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc."},"resource_id":{"type":"string","maxLength":100,"minLength":1,"title":"Resource Id","description":"Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'."},"operations":{"anyOf":[{"items":{"$ref":"#/components/schemas/NamespaceOperation"},"type":"array"},{"type":"null"}],"title":"Operations","description":"Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list."}},"type":"object","required":["resource_type","resource_id"],"title":"ResourceScope","description":"Fine-grained restriction applied to an API key.","examples":[{"description":"Full namespace access (data + infrastructure)","resource_id":"ns_production","resource_type":"namespace"},{"description":"Analytics-only access in namespace","operations":["read_data","execute_retriever"],"resource_id":"ns_customer_123","resource_type":"namespace"},{"description":"Specific collection only","resource_id":"col_products","resource_type":"collection"}]},"ResourceScope-Output":{"properties":{"resource_type":{"$ref":"#/components/schemas/shared__organizations__enums__ResourceType","description":"Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc."},"resource_id":{"type":"string","maxLength":100,"minLength":1,"title":"Resource Id","description":"Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'."},"operations":{"anyOf":[{"items":{"$ref":"#/components/schemas/NamespaceOperation"},"type":"array"},{"type":"null"}],"title":"Operations","description":"Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list."}},"type":"object","required":["resource_type","resource_id"],"title":"ResourceScope","description":"Fine-grained restriction applied to an API key.","examples":[{"description":"Full namespace access (data + infrastructure)","resource_id":"ns_production","resource_type":"namespace"},{"description":"Analytics-only access in namespace","operations":["read_data","execute_retriever"],"resource_id":"ns_customer_123","resource_type":"namespace"},{"description":"Specific collection only","resource_id":"col_products","resource_type":"collection"}]},"ResourceType-Input":{"type":"string","enum":["organization","user","api_key","namespace","collection","bucket","retriever","cluster","taxonomy","storage_connection","alert"],"title":"ResourceType","description":"Resource surfaces supported by scoped API keys and audit events.\n\nThese resource types can be used in:\n- API key scopes to restrict access to specific resources\n- Audit logs to identify what type of resource was affected\n- Permission systems to grant/deny access to resource categories\n\nResource hierarchy:\n ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION\n NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY\n\nResource types:\n - ORGANIZATION: Top-level tenant entity\n - USER: Organization member with authentication credentials\n - API_KEY: Authentication token for programmatic access\n - NAMESPACE: Isolated environment for data and compute resources\n - COLLECTION: Vector database collection for searchable documents\n - BUCKET: Object storage container for raw files\n - RETRIEVER: Configured search/retrieval pipeline\n - CLUSTER: Ray compute cluster for distributed processing\n - TAXONOMY: Hierarchical classification system for documents\n - STORAGE_CONNECTION: External storage provider integration"},"ResultCardProperties":{"properties":{"layout":{"type":"string","title":"Layout","description":"Card layout orientation","default":"vertical","examples":["vertical","horizontal"]},"show_thumbnail":{"type":"boolean","title":"Show Thumbnail","description":"Whether to show thumbnail image in results","default":true},"thumbnail_aspect_ratio":{"type":"string","title":"Thumbnail Aspect Ratio","description":"Aspect ratio for thumbnail images","default":"16/9","examples":["16/9","4/3","1/1"]},"thumbnail_fit":{"type":"string","title":"Thumbnail Fit","description":"How thumbnail should fit in container","default":"cover","examples":["cover","contain"]},"show_score":{"type":"boolean","title":"Show Score","description":"Whether to display relevance score","default":false},"truncate_title":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Truncate Title","description":"Maximum characters for title before truncation","examples":[60,80,100]},"truncate_description":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Truncate Description","description":"Maximum characters for description before truncation","examples":[120,150,200]},"field_order":{"items":{"type":"string"},"type":"array","title":"Field Order","description":"Order of fields to display in result card. Fields not in this list won't be shown. Must be subset of exposed_fields.","examples":[["title","description","category","created_at"],["thumbnail_url","title","price","views"]]},"show_find_similar":{"type":"boolean","title":"Show Find Similar","description":"Whether to show a 'Find Similar' button on result cards","default":false},"card_click_action":{"type":"string","title":"Card Click Action","description":"Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal)","default":"viewDetails","examples":["none","findSimilar","viewDetails"]},"thumbnail_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Field","description":"Field name to use as thumbnail image source","examples":["thumbnail_url","image_url","page_image"]},"title_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title Field","description":"Field name to use as card title","examples":["title","name","document_title"]},"card_fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Card Fields","description":"Fields to display on the card (alternative to field_order for template compatibility)","examples":[["title","description","price"]]},"modal_fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Modal Fields","description":"Fields to display in the detail modal when card is clicked","examples":[["title","description","full_text","metadata"]]},"card_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Style","description":"Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles","default":"default","examples":["default","portrait-discovery","media-search","document-search"]}},"type":"object","title":"ResultCardProperties","description":"Properties for result card display configuration.","examples":[{"card_click_action":"viewDetails","card_style":"default","field_order":["title","description","category","created_at"],"layout":"vertical","show_find_similar":true,"show_score":true,"show_thumbnail":true,"thumbnail_aspect_ratio":"16/9","thumbnail_field":"image_url","thumbnail_fit":"cover","title_field":"title","truncate_description":120,"truncate_title":60}]},"RetrieverAPIKeyListResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/APIKeyModel"},"type":"array","title":"Results","description":"List of API keys for the retriever (plaintext key never included)."},"total":{"type":"integer","title":"Total","description":"Total number of keys (including revoked if requested).","default":0}},"type":"object","title":"RetrieverAPIKeyListResponse","description":"Response for listing retriever API keys."},"RetrieverAPIKeyResponse":{"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":13,"minLength":10},{"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."},"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"]]},"key":{"type":"string","title":"Key","description":"Plaintext API key (shown only once). Prefix: ret_sk_. Store securely immediately after creation."}},"type":"object","required":["key_hash","internal_id","user_id","name","key"],"title":"RetrieverAPIKeyResponse","description":"Response model including the plaintext key (shown only once).\n\nThis response is returned immediately after key creation. The plaintext key\nis shown ONLY in this response and cannot be retrieved later. Users should\nsave the key immediately for secure storage.\n\nSecurity note:\n The `key` field contains the plaintext secret and should be:\n - Stored securely by the user (environment variables, secrets manager)\n - Never committed to version control\n - Never logged or exposed in error messages\n - Rotated/revoked if accidentally exposed","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"}]},"RetrieverConfig":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Stable retriever identifier (REQUIRED)."},"retriever_name":{"type":"string","minLength":1,"title":"Retriever Name","description":"Unique retriever name within namespace (REQUIRED)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Detailed description of retriever behaviour (OPTIONAL)."},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"Collections queried by the retriever. Can be empty for query-only inference mode."},"stages":{"items":{"$ref":"#/components/schemas/StageConfig"},"type":"array","minItems":1,"title":"Stages","description":"Ordered list of stage configurations (REQUIRED)."},"input_schema":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Output"},"type":"object","title":"Input Schema","description":"JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference."},"budget_limits":{"$ref":"#/components/schemas/BudgetLimits","description":"Execution budget limits for the retriever (OPTIONAL)."},"feature_dependencies":{"anyOf":[{"items":{"$ref":"#/components/schemas/FeatureAddress"},"type":"array"},{"type":"null"}],"title":"Feature Dependencies","description":"Feature addresses required by stages (OPTIONAL, aids validation)."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Arbitrary tags to help organise retrievers (OPTIONAL)."},"display_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Display Config","description":"Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever."},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Version number that increments on each update (REQUIRED).","default":1},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp in UTC (REQUIRED)."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp in UTC (REQUIRED)."},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Identifier of the user who created the retriever (OPTIONAL)."},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"Identifier of the user who last updated the retriever (OPTIONAL)."}},"type":"object","required":["retriever_name","stages"],"title":"RetrieverConfig","description":"Full retriever definition persisted in MongoDB.","examples":[{"budget_limits":{"max_credits":100,"max_time_ms":60000},"collection_ids":["col_marketing_ads"],"input_schema":{"query_text":{"description":"Full-text query","type":"string"}},"retriever_id":"ret_abc123","retriever_name":"executive_ads_search","stages":[{"config":{"parameters":{"field":"metadata.spend","operator":"gt","value":1000},"stage_name":"attribute_filter","version":"v1"},"name":"filter_high_spend","stage_type":"filter"}]}]},"RetrieverEnrichmentConfig-Input":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the retriever to execute","examples":["ret_classifier_001","ret_cross_reference"]},"input_mappings":{"items":{"$ref":"#/components/schemas/EnrichmentInputMapping"},"type":"array","minItems":1,"title":"Input Mappings","description":"Map document fields or constants to retriever input parameters"},"write_back_fields":{"items":{"$ref":"#/components/schemas/WriteBackFieldMapping"},"type":"array","minItems":1,"title":"Write Back Fields","description":"Which retriever result fields to write back to the document"},"execution_phase":{"$ref":"#/components/schemas/PostProcessingPhase","description":"Which phase this enrichment runs in. Default: RETRIEVER_ENRICHMENT (phase 4, after taxonomies, clusters, and alerts)","default":4},"priority":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Priority","description":"Priority within the execution phase (higher = runs first)","default":0},"scroll_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Optional filters to select which documents to enrich"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this enrichment is active","default":true}},"type":"object","required":["retriever_id","input_mappings","write_back_fields"],"title":"RetrieverEnrichmentConfig","description":"Configuration for attaching a retriever enrichment to a collection.\n\nRetriever enrichments run a retriever pipeline on each document during\npost-processing and write selected result fields back to the document.\n\nAttributes:\n retriever_id: ID of the retriever to execute\n input_mappings: How to map document fields to retriever inputs\n write_back_fields: Which result fields to write back to the document\n execution_phase: Which post-processing phase to run in (default: RETRIEVER_ENRICHMENT)\n priority: Priority within the execution phase (higher = runs first)\n scroll_filters: Optional filters to select which documents to enrich\n enabled: Whether this enrichment is active","examples":[{"enabled":true,"input_mappings":[{"input_key":"query","source":{"path":"title","source_type":"document_field"}}],"retriever_id":"ret_classifier_001","write_back_fields":[{"mode":"first","source_field":"category","target_field":"_enrichment_category"}]}]},"RetrieverEnrichmentConfig-Output":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"ID of the retriever to execute","examples":["ret_classifier_001","ret_cross_reference"]},"input_mappings":{"items":{"$ref":"#/components/schemas/EnrichmentInputMapping"},"type":"array","minItems":1,"title":"Input Mappings","description":"Map document fields or constants to retriever input parameters"},"write_back_fields":{"items":{"$ref":"#/components/schemas/WriteBackFieldMapping"},"type":"array","minItems":1,"title":"Write Back Fields","description":"Which retriever result fields to write back to the document"},"execution_phase":{"$ref":"#/components/schemas/PostProcessingPhase","description":"Which phase this enrichment runs in. Default: RETRIEVER_ENRICHMENT (phase 4, after taxonomies, clusters, and alerts)","default":4},"priority":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Priority","description":"Priority within the execution phase (higher = runs first)","default":0},"scroll_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"type":"null"}],"description":"Optional filters to select which documents to enrich"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this enrichment is active","default":true}},"type":"object","required":["retriever_id","input_mappings","write_back_fields"],"title":"RetrieverEnrichmentConfig","description":"Configuration for attaching a retriever enrichment to a collection.\n\nRetriever enrichments run a retriever pipeline on each document during\npost-processing and write selected result fields back to the document.\n\nAttributes:\n retriever_id: ID of the retriever to execute\n input_mappings: How to map document fields to retriever inputs\n write_back_fields: Which result fields to write back to the document\n execution_phase: Which post-processing phase to run in (default: RETRIEVER_ENRICHMENT)\n priority: Priority within the execution phase (higher = runs first)\n scroll_filters: Optional filters to select which documents to enrich\n enabled: Whether this enrichment is active","examples":[{"enabled":true,"input_mappings":[{"input_key":"query","source":{"path":"title","source_type":"document_field"}}],"retriever_id":"ret_classifier_001","write_back_fields":[{"mode":"first","source_field":"category","target_field":"_enrichment_category"}]}]},"RetrieverExecutionRequest":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs","description":"Runtime inputs for the retriever mapped to the input schema. Keys must match the retriever's input_schema field names. Values depend on field types (text, vector, filters, etc.). REQUIRED unless all retriever inputs have defaults. \n\nCommon input keys:\n- 'query': Text search query\n- 'embedding': Pre-computed vector for search\n- 'top_k': Number of results to return\n- 'min_score': Minimum relevance threshold\n- Any custom fields defined in input_schema\n\n\n**Template Syntax** (Jinja2):\n\nNamespaces (uppercase or lowercase):\n- `INPUT` / `input`: Query inputs (e.g., `{{INPUT.query}}`)\n- `DOC` / `doc`: Document fields (e.g., `{{DOC.payload.title}}`)\n- `CONTEXT` / `context`: Execution context\n- `STAGE` / `stage`: Stage configuration\n- `SECRET` / `secret`: Vault secrets (e.g., `{{SECRET.api_key}}`)\n\nAccessing Data:\n- Dot notation: `{{DOC.payload.metadata.title}}`\n- Bracket notation: `{{DOC.payload['special-key']}}`\n- Array index: `{{DOC.items[0]}}`, `{{DOC.tags[2]}}`\n- Array first/last: `{{DOC.items | first}}`, `{{DOC.items | last}}`\n\nArray Operations:\n- Iterate: `{% for item in DOC.tags %}{{item}}{% endfor %}`\n- Extract key: `{{DOC.items | map(attribute='name') | list}}`\n- Join: `{{DOC.tags | join(', ')}}`\n- Length: `{{DOC.items | length}}`\n- Slice: `{{DOC.items[:5]}}`\n\nConditionals:\n- If: `{% if DOC.status == 'active' %}...{% endif %}`\n- If-else: `{% if DOC.score > 0.8 %}high{% else %}low{% endif %}`\n- Ternary: `{{'yes' if DOC.enabled else 'no'}}`\n\nBuilt-in Functions: `max`, `min`, `abs`, `round`, `ceil`, `floor`\nCustom Filters: `slugify` (URL-safe), `bool` (truthy coercion), `tojson` (JSON encode)\n\nS3 URLs: Internal S3 URLs (s3://bucket/key) are automatically presigned when accessed via DOC namespace.","examples":[{"query":"artificial intelligence","top_k":25},{"min_score":0.7,"query":"customer feedback","top_k":50},{"category":"blog","embedding":[0.1,0.2,0.3],"top_k":10}]},"pagination":{"anyOf":[{"$ref":"#/components/schemas/OffsetPaginationParams"},{"$ref":"#/components/schemas/CursorPaginationParams"},{"$ref":"#/components/schemas/ScrollPaginationParams"},{"$ref":"#/components/schemas/KeysetPaginationParams"}],"title":"Pagination","description":"Pagination strategy configuration. Defaults to cursor-based pagination with limit=20. \n\nIMPORTANT: Pagination params do NOT support template variables ({{INPUT.x}} or {{DOCUMENT.x}}). Pagination is a request-level parameter for slicing results, separate from pipeline business logic. Pass cursor/limit values directly from your client code. Cursor values come from the previous response's pagination.cursor field.\n\nSupported Methods:\n- CURSOR (default): Best for infinite scroll, stateless, opaque token\n- KEYSET: Most efficient, requires stable sort, stateless\n- OFFSET: Traditional page numbers, can have drift issues\n- SCROLL: Server-side state, best for bulk exports\n\n\nUse CURSOR for:\n- Infinite scroll UIs (mobile apps, feeds, timelines)\n- Real-time updates where consistency matters\n- When you can't jump to arbitrary pages\n\n\nUse KEYSET for:\n- Maximum performance with large result sets\n- Stable sort fields (e.g., score DESC, id ASC)\n- When you need truly stateless pagination\n\n\nUse OFFSET for:\n- Traditional page UIs with page numbers\n- When users need to jump to specific pages\n- Smaller result sets where drift is acceptable\n\n\nUse SCROLL for:\n- Bulk exports or processing large datasets\n- When you need to iterate through all results\n- Background jobs with progress tracking\n\n\nExample (cursor - first page):\n{\"method\": \"cursor\", \"limit\": 20, \"cursor\": null}\n\nExample (cursor - next page, using cursor from previous response):\n{\"method\": \"cursor\", \"limit\": 20, \"cursor\": \"eyJvZmZzZXQiOjIwfQ==\"}\n\nExample (offset):\n{\"method\": \"offset\", \"page_size\": 25, \"page_number\": 2}\n\nExample (keyset):\n{\"method\": \"keyset\", \"limit\": 20, \"after\": {\"score\": 0.73, \"id\": \"doc_20\"}}\n"},"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 uses text/event-stream content type\n- Each stage completion emits a StreamStageEvent\n- Events include: stage_start, stage_complete, stage_error, execution_complete\n- Clients receive intermediate results and statistics as stages execute\n- Useful for progress tracking, debugging, and partial result display\n\n\nWhen stream=False (default):\n- Response returns after all stages complete\n- Returns a single RetrieverExecutionResponse with final results\n- Lower overhead for simple queries\n\n\nUse streaming when:\n- You want to show real-time progress to users\n- You need to display intermediate results\n- Pipeline has many stages or long-running operations\n- Debugging or monitoring pipeline performance\n\n\nExample streaming client (JavaScript):\n```javascript\nconst eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true');\neventSource.onmessage = (event) => {\n const stageEvent = JSON.parse(event.data);\n if (stageEvent.event_type === 'stage_complete') {\n console.log(`Stage ${stageEvent.stage_name} completed`);\n console.log(`Documents: ${stageEvent.documents.length}`);\n }\n};\n```\n\n\nExample streaming client (Python):\n```python\nimport requests\nresponse = requests.post('/v1/retrievers/ret_123/execute',\n json={'inputs': {...}, 'stream': True},\n stream=True)\nfor line in response.iter_lines():\n if line.startswith(b'data: '):\n event = json.loads(line[6:])\n print(f\"Stage {event['stage_name']}: {event['event_type']}\")\n```","default":false,"examples":[false,true]}},"type":"object","title":"RetrieverExecutionRequest","description":"Request payload for executing a retriever.\n\nExecutes a predefined retriever with runtime inputs. The retriever uses the\ncollections it was created with - collection overrides are not supported at\nexecution time to ensure feature_uri and schema validation integrity.\n\nAll filtering, pagination, and result shaping is handled by the individual stages\nbased on the inputs provided.\n\nUse Cases:\n - Execute retriever with its configured collections\n - Pass inputs that stages use to determine filtering/pagination behavior\n\nDesign Philosophy:\n - Retrievers are validated at creation time against their collections\n - Feature URIs, input schemas, and stage configs are tightly coupled to collections\n - Filters, limits, and offsets are NOT top-level request fields\n - These are handled by stages when they receive inputs\n - Example: A stage might read {INPUT.top_k} to determine result limit\n\nExamples:\n Simple query:\n {\"inputs\": {\"query\": \"AI\", \"top_k\": 50}}\n\n Different inputs for stage behavior:\n {\"inputs\": {\n \"query\": \"machine learning\",\n \"top_k\": 100,\n \"min_score\": 0.7,\n \"published_after\": \"2024-01-01\"\n }}","examples":[{"description":"Simple query","inputs":{"query":"artificial intelligence trends","top_k":25}},{"description":"Query with stage-driven filtering via inputs","inputs":{"categories":["AI","ML"],"min_score":0.7,"published_after":"2024-01-01","query":"machine learning","top_k":100}},{"description":"Advanced query with multiple input parameters","inputs":{"date_range":{"end":"2024-12-31","start":"2024-01-01"},"query":"customer testimonials","sentiment":"positive","top_k":20}},{"description":"Infinite scroll with cursor pagination (first page)","inputs":{"query":"AI trends","top_k":50},"pagination":{"limit":20,"method":"cursor"}},{"description":"Infinite scroll (next page using cursor from previous response)","inputs":{"query":"AI trends","top_k":50},"pagination":{"cursor":"eyJvZmZzZXQiOjIwfQ==","limit":20,"method":"cursor"}},{"description":"Traditional pagination with page numbers","inputs":{"query":"ML papers"},"pagination":{"method":"offset","page_number":2,"page_size":25}},{"description":"High-performance keyset pagination","inputs":{"query":"customer reviews","top_k":100},"pagination":{"after":{"id":"doc_20","score":0.73},"limit":20,"method":"keyset"}},{"description":"Scroll pagination for bulk export","inputs":{"query":"all documents"},"pagination":{"limit":100,"method":"scroll","scroll_ttl":300}}]},"RetrieverExecutionStatistics":{"properties":{"stages":{"additionalProperties":{"$ref":"#/components/schemas/StageStatistics"},"type":"object","title":"Stages","description":"Per-stage statistics keyed by stage instance name (REQUIRED)."},"total_time_ms":{"type":"number","minimum":0.0,"title":"Total Time Ms","description":"Total retriever execution time in milliseconds (REQUIRED).","default":0.0},"credits_used":{"type":"number","minimum":0.0,"title":"Credits Used","description":"Total credits consumed across all stages (OPTIONAL in MVP).","default":0.0}},"type":"object","title":"RetrieverExecutionStatistics","description":"Aggregated execution statistics for an entire retriever execution run."},"RetrieverExecutionSummary":{"properties":{"execution_id":{"type":"string","title":"Execution Id","description":"Execution identifier"},"status":{"type":"string","title":"Status","description":"Execution status"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Completion timestamp when available"},"duration_ms":{"type":"number","minimum":0.0,"title":"Duration Ms","description":"Total execution time in ms"},"credits_used":{"type":"number","minimum":0.0,"title":"Credits Used","description":"Credits consumed"},"total_processed":{"type":"integer","minimum":0.0,"title":"Total Processed","description":"Documents processed across stages"},"total_returned":{"type":"integer","minimum":0.0,"title":"Total Returned","description":"Documents returned to caller"},"cache_hit_rate":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Cache Hit Rate","description":"Average cache hit rate for stages"},"inputs_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inputs Hash","description":"Stable hash of retriever inputs for dedupe"},"query_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Summary","description":"Representative snippet of query inputs"}},"type":"object","required":["execution_id","status","created_at","duration_ms","credits_used","total_processed","total_returned"],"title":"RetrieverExecutionSummary","description":"Summary document used for execution history listings."},"RetrieverInputSchemaField-Input":{"properties":{"type":{"$ref":"#/components/schemas/RetrieverInputSchemaFieldType"},"default":{"anyOf":[{},{"type":"null"}],"title":"Default"},"items":{"anyOf":[{"$ref":"#/components/schemas/RetrieverInputSchemaField-Input"},{"type":"null"}]},"properties":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-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":"RetrieverInputSchemaField","description":"Schema field definition for retriever input parameters.\n\nIdentical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType\nwhich includes additional reference types like document_reference.\n\nThis allows retrievers to accept:\n1. Metadata inputs (strings, numbers, dates, etc.)\n2. File inputs (images, videos, documents for search)\n3. Reference inputs (document_reference for \"find similar\" queries)"},"RetrieverInputSchemaField-Output":{"properties":{"type":{"$ref":"#/components/schemas/RetrieverInputSchemaFieldType"},"default":{"anyOf":[{},{"type":"null"}],"title":"Default"},"items":{"anyOf":[{"$ref":"#/components/schemas/RetrieverInputSchemaField-Output"},{"type":"null"}]},"properties":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-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":"RetrieverInputSchemaField","description":"Schema field definition for retriever input parameters.\n\nIdentical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType\nwhich includes additional reference types like document_reference.\n\nThis allows retrievers to accept:\n1. Metadata inputs (strings, numbers, dates, etc.)\n2. File inputs (images, videos, documents for search)\n3. Reference inputs (document_reference for \"find similar\" queries)"},"RetrieverInputSchemaFieldType":{"type":"string","enum":["string","number","integer","float","boolean","object","array","date","datetime","text","image","audio","video","pdf","excel","document_reference"],"title":"RetrieverInputSchemaFieldType","description":"Supported data types for retriever input schema fields.\n\nRetriever input schemas define what parameters users can provide when executing\na retriever. This includes all bucket schema types plus additional reference types.\n\nTypes fall into three categories:\n\n1. **Metadata Types** (JSON types):\n - Standard JSON-compatible types\n - Examples: string, number, boolean, date\n - Inherited from BucketSchemaFieldType\n\n2. **File Types** (blobs):\n - Users can upload files/content as search inputs\n - Examples: text, image, video, pdf\n - Inherited from BucketSchemaFieldType\n\n3. **Reference Types** (structured metadata):\n - Special types for referencing existing documents\n - Examples: document_reference\n - Only available in retriever input schemas (NOT in bucket schemas)\n\n**DOCUMENT_REFERENCE Usage**:\n Accept document reference for \"find similar\" queries.\n\n Example - Find similar products retriever:\n {\n \"reference_product\": {\n \"type\": \"document_reference\",\n \"description\": \"Find products similar to this one\",\n \"required\": true\n }\n }\n\n Execution input:\n {\n \"inputs\": {\n \"reference_product\": {\n \"collection_id\": \"col_products\",\n \"document_id\": \"doc_item_123\"\n }\n }\n }\n\n The system will use the pre-computed features from doc_item_123\n to find similar documents without re-processing."},"RetrieverMetadata":{"properties":{"stages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Stages","description":"Pipeline stages used in this retriever","examples":[[{"stage_name":"feature_filter","stage_type":"filter"},{"stage_name":"llm_filter","stage_type":"filter"}]]},"collections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Collections","description":"Collections and feature extractors used","examples":[[{"collection_id":"col_abc123","collection_name":"Products","feature_extractor":{"name":"multimodal_extractor","version":"v1"}}]]},"capabilities":{"additionalProperties":true,"type":"object","title":"Capabilities","description":"Capabilities and features of this retriever","examples":[{"multi_stage_pipeline":true,"stage_count":2,"supports_image_search":true,"supports_text_search":true}]}},"type":"object","title":"RetrieverMetadata","description":"Metadata explaining how the retriever works.\n\nThis is separate from DisplayConfig and provides technical information\nabout the retriever's architecture for developers/debugging."},"RetrieverModel-Input":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Unique identifier for the retriever"},"retriever_name":{"type":"string","title":"Retriever Name","description":"Name of the retriever"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the retriever"},"visibility":{"$ref":"#/components/schemas/RetrieverVisibility","description":"Visibility level: PRIVATE (owner only), PUBLIC (any valid API key), MARKETPLACE (requires subscription)","default":"private"},"marketplace_listing_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marketplace Listing Id","description":"Associated marketplace listing ID when visibility is MARKETPLACE"},"requires_subscription":{"type":"boolean","title":"Requires Subscription","description":"Whether this retriever requires an active subscription to access (marketplace only)","default":false},"input_schema":{"$ref":"#/components/schemas/RetrieverSchema","description":"Input schema for the retriever"},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"List of collection IDs"},"stages":{"items":{"$ref":"#/components/schemas/StageInstanceConfig"},"type":"array","title":"Stages","description":"List of stage configurations"},"cache_config":{"anyOf":[{"$ref":"#/components/schemas/CacheConfig"},{"type":"null"}],"description":"Cache configuration for this retriever. If not provided, caching is disabled."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the retriever was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the retriever was last modified"},"last_executed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Executed At","description":"When the retriever was last executed"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the retriever is enabled (can be toggled on/off)","default":true},"status":{"$ref":"#/components/schemas/RetrieverStatus","description":"Current operational status","default":"active"},"usage_stats":{"anyOf":[{"$ref":"#/components/schemas/UsageStatistics"},{"type":"null"}],"description":"Usage and performance statistics"},"collections":{"anyOf":[{"items":{"$ref":"#/components/schemas/CollectionDetail"},"type":"array"},{"type":"null"}],"title":"Collections","description":"Expanded collection details with names and metadata"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Custom key-value metadata"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for organization and filtering"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/CreatorInfo"},{"type":"null"}],"description":"Information about who created this retriever"},"updated_by":{"anyOf":[{"$ref":"#/components/schemas/CreatorInfo"},{"type":"null"}],"description":"Information about who last updated this retriever"},"version":{"type":"integer","title":"Version","description":"Version number (increments on each update)","default":1},"revision_history":{"items":{"$ref":"#/components/schemas/RevisionHistoryEntry"},"type":"array","title":"Revision History","description":"History of changes (optional, last N changes)"},"health":{"anyOf":[{"$ref":"#/components/schemas/HealthCheck"},{"type":"null"}],"description":"Health status and diagnostics"}},"type":"object","required":["retriever_name","input_schema","collection_ids","stages"],"title":"RetrieverModel","description":"Retriever model."},"RetrieverModel-Output":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Stable retriever identifier (REQUIRED)."},"retriever_name":{"type":"string","minLength":1,"title":"Retriever Name","description":"Unique retriever name within namespace (REQUIRED)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Detailed description of retriever behaviour (OPTIONAL)."},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"Collections queried by the retriever. Can be empty for query-only inference mode."},"stages":{"items":{"$ref":"#/components/schemas/StageConfig"},"type":"array","minItems":1,"title":"Stages","description":"Ordered list of stage configurations (REQUIRED)."},"input_schema":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Output"},"type":"object","title":"Input Schema","description":"JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference."},"budget_limits":{"$ref":"#/components/schemas/BudgetLimits","description":"Execution budget limits for the retriever (OPTIONAL)."},"feature_dependencies":{"anyOf":[{"items":{"$ref":"#/components/schemas/FeatureAddress"},"type":"array"},{"type":"null"}],"title":"Feature Dependencies","description":"Feature addresses required by stages (OPTIONAL, aids validation)."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Arbitrary tags to help organise retrievers (OPTIONAL)."},"display_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Display Config","description":"Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever."},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Version number that increments on each update (REQUIRED).","default":1},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp in UTC (REQUIRED)."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp in UTC (REQUIRED)."},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Identifier of the user who created the retriever (OPTIONAL)."},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"Identifier of the user who last updated the retriever (OPTIONAL)."},"is_published":{"type":"boolean","title":"Is Published","description":"Whether this retriever is currently published (either as public retriever or in marketplace)","default":false},"marketplace_listing_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marketplace Listing Id","description":"Marketplace listing ID if this retriever is published to the marketplace, None otherwise"}},"type":"object","required":["retriever_name","stages"],"title":"RetrieverModel","description":"Retriever configuration model exposed via API.","examples":[{"budget_limits":{"max_credits":100,"max_time_ms":60000},"collection_ids":["col_marketing_ads"],"input_schema":{"query_text":{"description":"Full-text query","type":"string"}},"retriever_id":"ret_abc123","retriever_name":"executive_ads_search","stages":[{"config":{"parameters":{"field":"metadata.spend","operator":"gt","value":1000},"stage_name":"attribute_filter","version":"v1"},"name":"filter_high_spend","stage_type":"filter"}]}]},"RetrieverOptions":{"properties":{"preserve_retriever_ids":{"type":"boolean","title":"Preserve Retriever Ids","description":"Keep same retriever IDs (avoid conflicts)","default":false},"migrate_interactions":{"type":"boolean","title":"Migrate Interactions","description":"Migrate user interaction data","default":false},"migrate_execution_history":{"type":"boolean","title":"Migrate Execution History","description":"Migrate past execution history","default":false},"validate_references":{"type":"boolean","title":"Validate References","description":"Pre-flight check all references exist","default":true}},"type":"object","title":"RetrieverOptions","description":"Options for retriever migration."},"RetrieverPerformanceResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Retriever identifier","examples":["ret_abc123"]},"time_range":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Time range of the data"},"metrics":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Metrics","description":"Time-series performance metrics"},"summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Summary","description":"Aggregated summary statistics"}},"type":"object","required":["retriever_id","time_range","metrics"],"title":"RetrieverPerformanceResponse","description":"Retriever performance metrics response.","examples":[{"metrics":[{"avg_latency_ms":145.3,"avg_results":10.5,"p95_latency_ms":287.5,"p99_latency_ms":456.2,"query_count":245,"time_bucket":"2025-10-28T00:00:00Z"}],"retriever_id":"ret_abc123","summary":{"avg_latency_ms":152.8,"p95_latency_ms":295.2,"p99_latency_ms":502.1,"total_queries":5234},"time_range":{"end":"2025-10-29T00:00:00Z","start":"2025-10-28T00:00:00Z"}}]},"RetrieverSchema":{"properties":{"properties":{"additionalProperties":{"$ref":"#/components/schemas/RetrieverInputSchemaField-Input"},"type":"object","title":"Properties","description":"Schema properties for retriever inputs"}},"additionalProperties":true,"type":"object","title":"RetrieverSchema","description":"Schema definition for retriever inputs."},"RetrieverSignal":{"properties":{"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Event timestamp"},"execution_id":{"type":"string","title":"Execution Id","description":"Execution identifier"},"signal_type":{"type":"string","title":"Signal Type","description":"Type of signal","examples":["cache_hit","rerank_scores","filter_reduction"]},"signal_data":{"additionalProperties":true,"type":"object","title":"Signal Data","description":"Signal-specific data"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional metadata"}},"type":"object","required":["timestamp","execution_id","signal_type","signal_data"],"title":"RetrieverSignal","description":"Single retriever signal event."},"RetrieverStageDefinition":{"properties":{"stage_id":{"type":"string","title":"Stage Id","description":"REQUIRED. Unique identifier for the stage type. Use this ID in the 'stage_id' field when configuring stages in a retriever. Common stage IDs: 'attribute_filter', 'feature_filter', 'llm_filter', 'sort_relevance', 'document_enrich', 'taxonomy_enrich'. Stage IDs are immutable and versioned separately from implementation.","examples":["attribute_filter","feature_filter","llm_filter","sort_relevance","document_enrich"]},"description":{"type":"string","title":"Description","description":"REQUIRED. Human-readable description of what the stage does. Explains the stage's purpose, behavior, and when to use it. Use this to understand stage capabilities before using in pipelines.","examples":["Filter documents by attribute conditions with boolean logic","Unified multi-vector search with N feature URIs and fusion","Filter documents using LLM-based reasoning and natural language criteria","Sort documents by relevance scores"]},"category":{"$ref":"#/components/schemas/StageCategory","description":"REQUIRED. Transformation category defining how the stage processes documents. Categories: 'filter' (subset, Nā†’ā‰¤N), 'sort' (reorder, Nā†’N), 'reduce' (aggregate, Nā†’1), 'apply' (enrich/expand, Nā†’N or Nā†’N*M). Use category to understand stage's impact on document flow.","examples":["filter","sort","reduce","apply"]},"icon":{"type":"string","title":"Icon","description":"REQUIRED. Lucide React icon identifier for UI rendering. Used by frontend clients to display stage icons in pipeline builders. See https://lucide.dev for available icon names. Common icons: 'filter' (attribute_filter), 'search' (semantic), 'brain-circuit' (LLM), 'arrow-up-down' (sort).","examples":["filter","search","brain-circuit","arrow-up-down","database"]},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema","description":"OPTIONAL. JSON Schema defining the parameters this stage accepts. Contains full Pydantic schema including types, descriptions, examples, and validation rules for all stage parameters. Use this schema to validate stage configurations before submission. Null if stage requires no parameters (rare). Schema includes: field types, required fields, defaults, validation constraints, field descriptions, and usage examples.","examples":[{"properties":{"field":{"description":"Dot-delimited field path to evaluate","examples":["metadata.status","metadata.priority"],"type":"string"},"operator":{"description":"Comparison operator","enum":["eq","ne","gt","gte","lt","lte","in","nin"]},"value":{"description":"Comparison value (type depends on field)"}},"required":["field","operator","value"],"type":"object"},null]}},"type":"object","required":["stage_id","description","category","icon"],"title":"RetrieverStageDefinition","description":"Public definition of a retriever stage available in the system.\n\nEach stage represents a specific operation in a retrieval pipeline (filter, sort,\nenrich, etc). Use the `/v1/retrievers/stages` endpoint to discover available stages\nand their parameter schemas before creating retrievers.\n\nStage Registration:\n - Stages are registered in the retriever stage registry\n - Each stage has a unique ID, category, and parameter schema\n - Parameter schemas are Pydantic models with full validation\n\nUsage Flow:\n 1. Call GET /v1/retrievers/stages to list all available stages\n 2. Review parameter_schema for each stage to understand requirements\n 3. Compose stages into a retrieval pipeline\n 4. Create retriever via POST /v1/collections/{id}/retrievers\n\nExample Workflow:\n ```\n # 1. Discover stages\n GET /v1/retrievers/stages\n\n # 2. Review attribute_filter schema\n {\n \"stage_id\": \"attribute_filter\",\n \"description\": \"Filter documents by attribute conditions\",\n \"category\": \"filter\",\n \"parameter_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"field\": {\"type\": \"string\"},\n \"operator\": {\"enum\": [\"eq\", \"ne\", \"gt\", \"gte\", \"lt\", \"lte\", \"in\", \"nin\"]},\n \"value\": {}\n }\n }\n }\n\n # 3. Create retriever using discovered stage\n POST /v1/collections/col_123/retrievers\n {\n \"stages\": [\n {\n \"stage_name\": \"filter_active\",\n \"stage_type\": \"filter\",\n \"config\": {\n \"stage_id\": \"attribute_filter\",\n \"parameters\": {\n \"field\": \"status\",\n \"operator\": \"eq\",\n \"value\": \"active\"\n }\n }\n }\n ]\n }\n ```\n\nRequirements:\n - stage_id: REQUIRED, unique identifier for the stage\n - description: REQUIRED, human-readable description of stage purpose\n - category: REQUIRED, transformation category (filter/sort/reduce/apply)\n - icon: REQUIRED, UI icon identifier (Lucide React)\n - parameter_schema: OPTIONAL, JSON Schema for stage parameters (null if no params)","examples":[{"category":"filter","description":"Filter documents by attribute conditions with boolean logic (AND/OR/NOT). Fast, operates on metadata fields.","icon":"filter","parameter_schema":{"properties":{"field":{"description":"Dot-delimited field path","examples":["metadata.status","metadata.category"],"type":"string"},"operator":{"description":"Comparison operator","enum":["eq","ne","gt","gte","lt","lte"]},"value":{"description":"Comparison value"}},"required":["field","operator","value"],"type":"object"},"stage_id":"attribute_filter"},{"category":"filter","description":"Filter documents using LLM-based reasoning. Slow but powerful for complex semantic filtering.","icon":"brain-circuit","parameter_schema":{"properties":{"provider":{"description":"LLM provider (google, openai, anthropic)","examples":["google","openai","anthropic"],"type":"string"},"model_name":{"description":"Specific model name","examples":["gemini-2.5-flash","gpt-4o-mini","claude-3-5-haiku-20241022"],"type":"string"},"criteria":{"description":"Natural language filtering criteria","examples":["Keep only enterprise-focused content","Discard negative sentiment"],"type":"string"}},"required":["criteria"],"type":"object"},"stage_id":"llm_filter"},{"category":"sort","description":"Sort documents by relevance scores in ascending or descending order.","icon":"arrow-up-down","parameter_schema":{"properties":{"order":{"default":"desc","description":"Sort order","enum":["asc","desc"]}},"type":"object"},"stage_id":"sort_relevance"}]},"RetrieverStatus":{"type":"string","enum":["active","draft","disabled","error"],"title":"RetrieverStatus","description":"Status of a retriever."},"RetrieverVisibility":{"type":"string","enum":["private","public","marketplace"],"title":"RetrieverVisibility","description":"Visibility level of a retriever determining who can access it."},"RetryBatchRequest":{"properties":{"retry_mode":{"type":"string","enum":["transient_only","all"],"title":"Retry Mode","description":"Determines which types of failed documents to retry. 'transient_only': Only retry documents that failed with transient errors (network issues, timeouts, rate limits). This is the recommended default as it avoids retrying documents with permanent failures (invalid data, missing fields, incompatible formats). 'all': Retry all failed documents regardless of error type. Use this for force retries after fixing data issues or updating extraction logic.","default":"transient_only","examples":["transient_only","all"]},"tier_nums":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Tier Nums","description":"List of specific tier numbers to retry failures from. OPTIONAL - If not provided or empty list, retries failures from all tiers. Use this to selectively retry a specific processing stage. Example: [2] would only retry failures from tier 2 (the third processing stage). Tier numbering starts at 0 (bucket ā†’ collection), tier 1+ are collection ā†’ collection.","examples":[[2],[1,2],null]},"max_retry_count":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Retry Count","description":"Maximum number of times a document can be retried. Documents that have been retried this many times already are excluded. Prevents infinite retry loops for documents with persistent issues. Default is 3 retries per document. Set to higher value for more aggressive retries.","default":3,"examples":[3,5,1]}},"type":"object","title":"RetryBatchRequest","description":"Request to retry failed documents in a batch.\n\nAllows selective retry of failed documents with intelligent filtering by error type\nand tier. Retries use exponential backoff and respect max retry limits.\n\nUse Cases:\n - Retry only transient errors after resolving temporary infrastructure issues\n - Retry specific processing tiers that failed\n - Retry all failed documents regardless of error type (force retry)\n\nRequirements:\n - retry_mode: REQUIRED. Determines which documents to retry\n - tier_nums: OPTIONAL. Only retry failures from specific tiers (empty = all tiers)\n - max_retry_count: OPTIONAL. Skip documents that have been retried this many times\n\nBehavior:\n - 'transient_only': Retries only transient errors (network, timeout, rate limit)\n - 'all': Retries both transient and permanent errors\n - Documents beyond max_retry_count are excluded from retry\n - Each retry increments the document's retry_count","examples":[{"description":"Retry only transient errors (default, recommended)","retry_mode":"transient_only"},{"description":"Retry only tier 2 transient failures","retry_mode":"transient_only","tier_nums":[2]},{"description":"Force retry all failures (after fixing data issues)","retry_mode":"all"},{"description":"Aggressive retry with higher max attempts","max_retry_count":5,"retry_mode":"transient_only"}]},"RevisionHistoryEntry":{"properties":{"version":{"type":"integer","title":"Version","description":"Version number"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When this version was created"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By","description":"User who made the change"},"changes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Changes","description":"Description of changes made"}},"type":"object","required":["version","updated_at"],"title":"RevisionHistoryEntry","description":"A single entry in the revision history."},"S3AccessKeyCredentials":{"properties":{"type":{"type":"string","const":"access_key","title":"Type","default":"access_key"},"access_key_id":{"type":"string","maxLength":128,"minLength":16,"title":"Access Key Id","description":"REQUIRED. AWS access key ID for authentication. Format: 20-character alphanumeric string starting with 'AKIA' (long-term) or 'ASIA' (temporary). Obtain from: AWS Console > IAM > Users > Security Credentials","examples":["AKIAIOSFODNN7EXAMPLE","ASIAIOSFODNN7EXAMPLE"]},"secret_access_key":{"type":"string","minLength":40,"title":"Secret Access Key","description":"REQUIRED. AWS secret access key for authentication. SECURITY: This field is encrypted at rest. Never log or expose this value. Format: 40-character base64-encoded string. Obtain from: AWS Console when creating/viewing access key (shown only once)"},"session_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Token","description":"NOT REQUIRED. Temporary session token for AWS STS credentials. REQUIRED when using temporary security credentials from AWS STS. NOT REQUIRED for long-term IAM user access keys. SECURITY: Encrypted at rest. Automatically expires after session duration. Format: Base64-encoded string, typically several hundred characters. Use case: Enhanced security with automatic credential rotation"}},"type":"object","required":["access_key_id","secret_access_key"],"title":"S3AccessKeyCredentials","description":"AWS S3 access key and secret credentials.\n\nAccess keys provide programmatic access to S3 buckets using long-lived credentials.\nThis authentication method is straightforward but less secure than IAM role assumption.\n\nPrerequisites:\n - IAM user or role with S3 access permissions\n - Access key and secret key generated in AWS Console\n - Appropriate bucket policies or IAM policies configured\n\nSecurity Considerations:\n - Access keys are long-lived and don't automatically expire\n - secret_access_key is encrypted at rest but should be rotated regularly\n - Consider using IAM role assumption (S3RoleCredentials) for production\n - Never commit access keys to version control\n\nUse Cases:\n - Quick prototyping and development\n - Testing S3 integrations\n - Temporary credentials with session_token for enhanced security\n - Accessing S3-compatible services (MinIO, DigitalOcean Spaces)\n\nRecommended Alternative:\n For production deployments, use S3RoleCredentials with IAM role assumption\n instead of access keys for better security and credential management."},"S3Config":{"properties":{"provider_type":{"type":"string","const":"s3","title":"Provider Type","default":"s3"},"credentials":{"oneOf":[{"$ref":"#/components/schemas/S3AccessKeyCredentials"},{"$ref":"#/components/schemas/S3RoleCredentials"}],"title":"Credentials","description":"REQUIRED. AWS authentication credentials configuration. Choose 'iam_role' for production deployments (recommended) or 'access_key' for development, testing, or S3-compatible services. The 'type' field determines which credential mechanism is used.","discriminator":{"propertyName":"type","mapping":{"access_key":"#/components/schemas/S3AccessKeyCredentials","iam_role":"#/components/schemas/S3RoleCredentials"}}},"region":{"type":"string","title":"Region","description":"REQUIRED. AWS region where the S3 bucket is located. Must match the bucket's actual region to avoid routing errors. For S3-compatible services, use their documented region value or 'us-east-1' as a default if regions are not applicable. Format: AWS region code (e.g., us-east-1, eu-west-1)","examples":["us-east-1","us-west-2","eu-west-1","ap-southeast-1","ca-central-1"]},"endpoint_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Url","description":"NOT REQUIRED for AWS S3 (uses default AWS endpoints). REQUIRED for S3-compatible services to specify custom endpoint URL. Must be a valid HTTPS or HTTP URL without trailing slash. Examples: - MinIO: https://minio.example.com - DigitalOcean Spaces: https://nyc3.digitaloceanspaces.com - Wasabi: https://s3.wasabisys.com","examples":["https://s3.wasabisys.com","https://nyc3.digitaloceanspaces.com","https://minio.company.com","http://localhost:9000"]},"use_ssl":{"type":"boolean","title":"Use Ssl","description":"Whether to use TLS/SSL encryption for connections to S3. RECOMMENDED: Always True for production environments. Set to False only for local development with unencrypted endpoints. Default: True","default":true},"verify_ssl":{"type":"boolean","title":"Verify Ssl","description":"Whether to verify TLS/SSL certificates when connecting. RECOMMENDED: Always True for production to prevent MITM attacks. Set to False only for development with self-signed certificates. Requires use_ssl=True to have any effect. Default: True","default":true}},"type":"object","required":["credentials","region"],"title":"S3Config","description":"Amazon S3 and S3-compatible storage provider configuration.\n\nThis configuration enables Mixpeek to connect to Amazon S3 or S3-compatible\nstorage services (MinIO, DigitalOcean Spaces, Wasabi, Backblaze B2, etc.)\nfor automated object ingestion and synchronization.\n\nAuthentication Methods:\n 1. IAM Role Assumption (RECOMMENDED for production):\n - Most secure option with automatic credential rotation\n - No long-lived credentials shared\n - Ideal for customer-owned S3 buckets\n\n 2. Access Keys:\n - Simpler setup for development and testing\n - Works with S3-compatible services\n - Requires manual credential rotation\n\nRequirements:\n - Valid AWS credentials or IAM role configuration\n - S3 bucket with appropriate permissions (s3:GetObject, s3:ListBucket)\n - Network connectivity to S3 endpoint\n - Correct region configuration\n\nSupported Services:\n - Amazon S3 (all regions)\n - MinIO (self-hosted or cloud)\n - DigitalOcean Spaces\n - Wasabi Cloud Storage\n - Backblaze B2\n - Any S3-compatible storage with compatible API\n\nUse Cases:\n - Ingest videos from data lakes\n - Sync images from marketing asset buckets\n - Process documents from archive storage\n - Monitor and index uploaded files\n - Backup and disaster recovery workflows","examples":[{"credentials":{"external_id":"mixpeek-org_abc123","role_arn":"arn:aws:iam::123456789012:role/mixpeek-storage-sync-role","type":"iam_role"},"description":"Production AWS S3 with IAM role (recommended)","provider_type":"s3","region":"us-east-1","use_ssl":true,"verify_ssl":true},{"credentials":{"access_key_id":"AKIAIOSFODNN7EXAMPLE","secret_access_key":"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY","type":"access_key"},"description":"Development AWS S3 with access keys","provider_type":"s3","region":"us-west-2","use_ssl":true,"verify_ssl":true},{"credentials":{"access_key_id":"minioadmin","secret_access_key":"minioadmin","type":"access_key"},"description":"MinIO self-hosted S3-compatible storage","endpoint_url":"https://minio.company.com","provider_type":"s3","region":"us-east-1","use_ssl":true,"verify_ssl":true},{"credentials":{"access_key_id":"DO00EXAMPLE","secret_access_key":"secretkeyexample123","type":"access_key"},"description":"DigitalOcean Spaces","endpoint_url":"https://nyc3.digitaloceanspaces.com","provider_type":"s3","region":"nyc3","use_ssl":true,"verify_ssl":true},{"credentials":{"access_key_id":"minioadmin","secret_access_key":"minioadmin","type":"access_key"},"description":"Local development MinIO without SSL","endpoint_url":"http://localhost:9000","provider_type":"s3","region":"us-east-1","use_ssl":false,"verify_ssl":false}]},"S3MetadataSource":{"properties":{"type":{"type":"string","const":"metadata","title":"Type","description":"Source type identifier. Must be 'metadata' for S3/Tigris user metadata.","default":"metadata"},"key":{"type":"string","maxLength":1024,"minLength":1,"title":"Key","description":"The metadata key to extract (without 'x-amz-meta-' prefix). Case-insensitive (S3 lowercases all metadata keys). Common examples: 'author', 'version', 'source-system', 'original-filename'. Note: S3 automatically lowercases keys, so 'Author' becomes 'author'.","examples":["author","version","original-filename","source-system"]}},"type":"object","required":["key"],"title":"S3MetadataSource","description":"Extract value from S3/Tigris object user metadata.\n\nS3 user metadata (x-amz-meta-*) provides custom key-value pairs stored\nwith the object. Unlike tags, metadata is set at upload time and is\nimmutable without re-uploading the object.\n\nProvider Compatibility: S3, Tigris, MinIO, DigitalOcean Spaces, Wasabi\n\nExample S3 CLI to set metadata:\n aws s3 cp video.mp4 s3://bucket/ --metadata '{\"author\":\"john\",\"version\":\"1.0\"}'\n\nExample boto3 upload with metadata:\n s3.put_object(Bucket='b', Key='k', Body=data, Metadata={'author': 'john'})\n\nExample mapping:\n {\"type\": \"metadata\", \"key\": \"author\"} -> extracts \"john\" from x-amz-meta-author\n\nAttributes:\n type: Must be \"metadata\" to identify this source type\n key: The metadata key without 'x-amz-meta-' prefix (case-insensitive)"},"S3RoleCredentials":{"properties":{"type":{"type":"string","const":"iam_role","title":"Type","default":"iam_role"},"role_arn":{"type":"string","pattern":"^arn:aws:iam::\\d{12}:role/[\\w+=,.@-]+$","title":"Role Arn","description":"REQUIRED. Amazon Resource Name (ARN) of the IAM role to assume. This role must exist in the customer's AWS account and have a trust relationship configured to allow Mixpeek to assume it. Format: arn:aws:iam::{account-id}:role/{role-name} Example trust policy should allow principal: arn:aws:iam::{mixpeek-account}:root Recommended role name: mixpeek-storage-sync-role","examples":["arn:aws:iam::123456789012:role/mixpeek-storage-sync-role","arn:aws:iam::999888777666:role/external-ingestion-access"]},"external_id":{"type":"string","maxLength":128,"minLength":8,"title":"External Id","description":"REQUIRED. External ID for secure role assumption (prevents confused deputy attacks). This value should be unique to your organization and kept confidential. Mixpeek provides this value during connection setup. Must match the ExternalId condition in the role's trust policy. Format: Recommended pattern is mixpeek-{organization_id} Security: Include this in the trust policy Condition statement","examples":["mixpeek-org_abc123def456ghi","mixpeek-customer-enterprise-xyz"]}},"type":"object","required":["role_arn","external_id"],"title":"S3RoleCredentials","description":"AWS S3 IAM role assumption credentials (RECOMMENDED for production).\n\nIAM role assumption provides secure, temporary credentials for accessing customer\nS3 buckets without sharing long-lived access keys. This is the recommended\nauthentication method for production deployments.\n\nHow It Works:\n 1. Customer creates an IAM role in their AWS account\n 2. Role trust policy allows Mixpeek AWS account to assume the role\n 3. External ID provides additional security against confused deputy attacks\n 4. Mixpeek assumes the role and receives temporary credentials (auto-renewed)\n 5. Temporary credentials are used to access the customer's S3 bucket\n\nPrerequisites:\n 1. Create IAM role in customer AWS account\n 2. Attach policy granting s3:GetObject, s3:ListBucket permissions\n 3. Configure trust relationship to allow Mixpeek account\n 4. Use organization-specific external_id for security\n 5. Share role ARN with Mixpeek\n\nSecurity Advantages:\n - No long-lived credentials shared with third parties\n - Temporary credentials automatically rotate (1-hour sessions by default)\n - Customer retains full control and can revoke access anytime\n - External ID prevents confused deputy attacks\n - Audit trail in CloudTrail for all access\n\nUse Cases:\n - Production deployments accessing customer S3 buckets\n - Enterprise integrations requiring strong security\n - Multi-tenant environments with customer-owned storage\n - Compliance-sensitive workloads (HIPAA, SOC 2, etc.)","examples":[{"description":"Production role assumption with external ID","external_id":"mixpeek-org_abc123def456ghi","role_arn":"arn:aws:iam::123456789012:role/mixpeek-storage-sync-role","type":"iam_role"}],"trust_policy_example":{"Statement":[{"Action":"sts:AssumeRole","Condition":{"StringEquals":{"sts:ExternalId":"mixpeek-org_abc123def456ghi"}},"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::{mixpeek-account-id}:root"}}],"Version":"2012-10-17"}},"S3TagSource":{"properties":{"type":{"type":"string","const":"tag","title":"Type","description":"Source type identifier. Must be 'tag' for S3/Tigris object tags.","default":"tag"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key","description":"The tag key to extract. Case-sensitive. Must match the exact tag key on the S3/Tigris object. Common examples: 'category', 'project', 'owner', 'environment'. Maximum length: 128 characters.","examples":["category","project","content-type","cost-center"]}},"type":"object","required":["key"],"title":"S3TagSource","description":"Extract value from an S3/Tigris object tag.\n\nS3 object tags are key-value pairs attached to objects, commonly used for\ncategorization, cost allocation, and metadata. Tags are limited to 10 per object\nwith keys up to 128 chars and values up to 256 chars.\n\nProvider Compatibility: S3, Tigris, MinIO, DigitalOcean Spaces, Wasabi\n\nExample S3 CLI to set tag:\n aws s3api put-object-tagging --bucket my-bucket --key video.mp4 \\\n --tagging 'TagSet=[{Key=category,Value=marketing}]'\n\nExample mapping:\n {\"type\": \"tag\", \"key\": \"category\"} -> extracts \"marketing\" from the tag\n\nAttributes:\n type: Must be \"tag\" to identify this source type\n key: The tag key to extract (case-sensitive, max 128 chars)"},"SEOConfig":{"properties":{"meta_title":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Meta Title","description":"SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.","examples":["Fitness Video Search | Mixpeek","Product Catalog | Your Brand"]},"meta_description":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Meta Description","description":"Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.","examples":["Search and discover fitness videos using AI-powered semantic search.","Browse our product catalog with intelligent visual search."]},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords","description":"Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.","examples":[["fitness","yoga","workout","exercise videos"],["products","catalog","search","e-commerce"]]},"og_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Og Image Url","description":"URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.","examples":["https://mixpeek-public-pages.s3.amazonaws.com/org/ns/og/video-search/og.png"]},"og_image_alt":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Og Image Alt","description":"Alt text for OG image (accessibility and SEO)","examples":["Fitness video search interface","Product catalog preview"]},"og_type":{"type":"string","title":"Og Type","description":"Open Graph content type","default":"website","examples":["website","article","product"]},"twitter_card":{"type":"string","title":"Twitter Card","description":"Twitter card display style","default":"summary_large_image","examples":["summary","summary_large_image","app"]},"twitter_site":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Site","description":"Twitter @handle for the site","default":"@mixpeek","examples":["@mixpeek","@yourbrand"]},"twitter_creator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Creator","description":"Twitter @handle for content creator (optional)","examples":["@johndoe","@yourbrand"]},"robots":{"type":"string","title":"Robots","description":"Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.","default":"index, follow","examples":["index, follow","noindex, nofollow","index, nofollow"]},"canonical_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Url","description":"Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.","examples":["https://yourdomain.com/search","https://mxp.co/r/video-search"]},"site_name":{"type":"string","title":"Site Name","description":"Site name for OG tags and branding","default":"Mixpeek","examples":["Mixpeek","Your Brand","Company Name"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Content author/creator name","examples":["Mixpeek","Your Organization"]},"locale":{"type":"string","title":"Locale","description":"Content language/locale","default":"en_US","examples":["en_US","en_GB","es_ES","fr_FR"]},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logo Url","description":"URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.","examples":["https://example.com/logo.png","https://cdn.mixpeek.com/logos/acme.png"]},"favicon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon Url","description":"URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.","examples":["https://example.com/favicon.ico","https://cdn.mixpeek.com/icons/acme.png"]},"structured_data":{"$ref":"#/components/schemas/StructuredDataConfig","description":"Schema.org structured data for rich search results"}},"type":"object","title":"SEOConfig","description":"SEO configuration for public retriever discoverability.\n\nAuto-generated during publishing with sensible defaults inferred from\nthe retriever's display_config. All fields can be overridden manually.\n\nThis configuration controls how the public retriever appears in:\n- Search engine results (Google, Bing, etc.)\n- Social media shares (Twitter, Facebook, LinkedIn)\n- Link previews in messaging apps","examples":[{"author":"Mixpeek","favicon_url":"https://example.com/favicon.ico","keywords":["fitness","yoga","workout","exercise videos"],"locale":"en_US","logo_url":"https://example.com/logo.png","meta_description":"Search and discover fitness videos using AI-powered semantic search.","meta_title":"Fitness Video Search | Mixpeek","og_image_alt":"Fitness video search interface","og_image_url":"https://mixpeek-public-pages.s3.amazonaws.com/og.png","og_type":"website","robots":"index, follow","site_name":"Mixpeek","structured_data":{"additional_properties":{"applicationCategory":"Search"},"type":"WebApplication"},"twitter_card":"summary_large_image","twitter_site":"@mixpeek"}]},"SchemaMapping-Input":{"properties":{"mappings":{"additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/FieldMappingEntry"},{"$ref":"#/components/schemas/BlobMappingEntry"}],"discriminator":{"propertyName":"target_type","mapping":{"blob":"#/components/schemas/BlobMappingEntry","field":"#/components/schemas/FieldMappingEntry"}}},"type":"object","title":"Mappings","description":"Dictionary mapping target field names to their source extractors. Keys are bucket schema field names (e.g., 'content', 'category'). Values are mapping entries defining how to extract and store the data. At least one blob mapping (target_type='blob') is recommended for file syncs."}},"type":"object","required":["mappings"],"title":"SchemaMapping","description":"Complete schema mapping configuration for a sync.\n\nDefines how source data (files, tags, metadata, columns) maps to the\ntarget bucket schema. Each key is a target field/blob name in the bucket.\n\n**Key Concepts:**\n- Keys are target bucket schema field names\n- Values define the source and extraction method\n- At least one blob mapping is typically required for file syncs\n- Field mappings extract metadata alongside the file content\n\n**Provider Examples:**\n\n**S3/Tigris Video Sync:**\n```json\n{\n \"content\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"video\"\n },\n \"category\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"tag\", \"key\": \"category\"}\n },\n \"source_bucket\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"constant\", \"value\": \"production-videos\"}\n }\n}\n```\n\n**Snowflake Customer Table Sync:**\n```json\n{\n \"customer_name\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"column\", \"name\": \"NAME\"}\n },\n \"profile_image\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"column\", \"name\": \"AVATAR_URL\"},\n \"blob_type\": \"image\"\n },\n \"segment\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"column\", \"name\": \"CUSTOMER_SEGMENT\"},\n \"transform\": \"lowercase\"\n }\n}\n```\n\n**Google Drive with Folder Categories:**\n```json\n{\n \"content\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"auto\"\n },\n \"department\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"folder_path\", \"segment\": 0},\n \"transform\": \"lowercase\"\n },\n \"description\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"drive_property\", \"key\": \"description\"}\n }\n}\n```\n\nAttributes:\n mappings: Dictionary mapping target field names to their source extractors"},"SchemaMapping-Output":{"properties":{"mappings":{"additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/FieldMappingEntry"},{"$ref":"#/components/schemas/BlobMappingEntry"}],"discriminator":{"propertyName":"target_type","mapping":{"blob":"#/components/schemas/BlobMappingEntry","field":"#/components/schemas/FieldMappingEntry"}}},"type":"object","title":"Mappings","description":"Dictionary mapping target field names to their source extractors. Keys are bucket schema field names (e.g., 'content', 'category'). Values are mapping entries defining how to extract and store the data. At least one blob mapping (target_type='blob') is recommended for file syncs."}},"type":"object","required":["mappings"],"title":"SchemaMapping","description":"Complete schema mapping configuration for a sync.\n\nDefines how source data (files, tags, metadata, columns) maps to the\ntarget bucket schema. Each key is a target field/blob name in the bucket.\n\n**Key Concepts:**\n- Keys are target bucket schema field names\n- Values define the source and extraction method\n- At least one blob mapping is typically required for file syncs\n- Field mappings extract metadata alongside the file content\n\n**Provider Examples:**\n\n**S3/Tigris Video Sync:**\n```json\n{\n \"content\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"video\"\n },\n \"category\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"tag\", \"key\": \"category\"}\n },\n \"source_bucket\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"constant\", \"value\": \"production-videos\"}\n }\n}\n```\n\n**Snowflake Customer Table Sync:**\n```json\n{\n \"customer_name\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"column\", \"name\": \"NAME\"}\n },\n \"profile_image\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"column\", \"name\": \"AVATAR_URL\"},\n \"blob_type\": \"image\"\n },\n \"segment\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"column\", \"name\": \"CUSTOMER_SEGMENT\"},\n \"transform\": \"lowercase\"\n }\n}\n```\n\n**Google Drive with Folder Categories:**\n```json\n{\n \"content\": {\n \"target_type\": \"blob\",\n \"source\": {\"type\": \"file\"},\n \"blob_type\": \"auto\"\n },\n \"department\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"folder_path\", \"segment\": 0},\n \"transform\": \"lowercase\"\n },\n \"description\": {\n \"target_type\": \"field\",\n \"source\": {\"type\": \"drive_property\", \"key\": \"description\"}\n }\n}\n```\n\nAttributes:\n mappings: Dictionary mapping target field names to their source extractors"},"SchemaSyncRequest":{"properties":{"sample_size":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Sample Size","description":"Number of documents to sample for schema discovery","default":1000},"force":{"type":"boolean","title":"Force","description":"Force schema sync even if within debounce window. Default: false (respects 5-minute debounce)","default":false},"cascade_to_downstream":{"type":"boolean","title":"Cascade To Downstream","description":"Automatically update downstream collections that use this collection as source. Default: true","default":true}},"type":"object","title":"SchemaSyncRequest","description":"Request to sync a collection's schema by sampling documents.\n\nUsed by:\n- Manual API calls from users\n- Automatic triggers from BatchJobPoller"},"SchemaSyncResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether schema sync succeeded"},"collection_id":{"type":"string","title":"Collection Id","description":"Collection that was synced"},"schema_version":{"type":"integer","title":"Schema Version","description":"New schema version"},"previous_version":{"type":"integer","title":"Previous Version","description":"Previous schema version"},"fields_added":{"items":{"type":"string"},"type":"array","title":"Fields Added","description":"List of new fields discovered"},"fields_total":{"type":"integer","title":"Fields Total","description":"Total fields in output_schema"},"documents_sampled":{"type":"integer","title":"Documents Sampled","description":"Number of documents sampled"},"downstream_collections_updated":{"items":{"type":"string"},"type":"array","title":"Downstream Collections Updated","description":"Downstream collections that were updated"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional message or error"}},"type":"object","required":["success","collection_id","schema_version","previous_version","fields_total","documents_sampled"],"title":"SchemaSyncResponse","description":"Response from schema sync operation."},"SchemaSyncSkippedResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Request succeeded","default":true},"skipped":{"type":"boolean","title":"Skipped","description":"Schema sync was skipped","default":true},"reason":{"type":"string","title":"Reason","description":"Why sync was skipped"},"collection_id":{"type":"string","title":"Collection Id","description":"Collection ID"},"schema_version":{"type":"integer","title":"Schema Version","description":"Current schema version"},"last_sync":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Sync","description":"Last sync timestamp"}},"type":"object","required":["reason","collection_id","schema_version"],"title":"SchemaSyncSkippedResponse","description":"Response when schema sync was skipped (debounce or disabled)."},"ScrollPaginationParams":{"properties":{"method":{"$ref":"#/components/schemas/PaginationMethod","description":"Constant identifying scroll pagination (REQUIRED).","default":"scroll"},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Number of documents to fetch per scroll page (REQUIRED). Default: 100.","default":100},"scroll_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scroll Id","description":"Server-issued scroll session identifier (OPTIONAL). null for first request, then use scroll_id from response"},"scroll_ttl":{"type":"integer","maximum":3600.0,"minimum":60.0,"title":"Scroll Ttl","description":"Seconds to keep scroll context alive (REQUIRED). Default: 300 (5 minutes).","default":300}},"type":"object","title":"ScrollPaginationParams","description":"Scroll-style pagination maintaining server-side context for TTL.\n\nBest for: Bulk exports, batch processing, iterating through all results\n\nHow it works:\n- Server maintains a snapshot of results\n- First request: scroll_id=null, returns scroll_id\n- Subsequent requests: use scroll_id from response\n- Context expires after scroll_ttl seconds\n- Consistent view of data (point-in-time snapshot)\n\nTradeoffs:\n- Requires server-side state (memory/cache)\n- TTL means sessions can expire\n- Not suitable for long-lived sessions\n- Good for background jobs, not user-facing UIs\n\nUse when:\n- Exporting large datasets\n- Batch processing all results\n- Background jobs iterating through results\n- You need consistent point-in-time view\n\nExample flow:\n1. Request: {\"method\": \"scroll\", \"limit\": 100, \"scroll_id\": null}\n2. Response: {\"documents\": [...], \"scroll_id\": \"xyz789\", \"has_next\": true}\n3. Request: {\"method\": \"scroll\", \"limit\": 100, \"scroll_id\": \"xyz789\"}"},"SearchInteraction":{"properties":{"feature_id":{"type":"string","title":"Feature Id","description":"ID of the document/feature that was interacted with. REQUIRED. This should be the document_id returned in retriever results. Used to track which specific items users engage with.","examples":["doc_abc123","prod_xyz789","feat_12345"]},"interaction_type":{"items":{"$ref":"#/components/schemas/InteractionType"},"type":"array","minItems":1,"title":"Interaction Type","description":"List of interaction types that occurred. REQUIRED. Multiple types can be recorded simultaneously (e.g., VIEW + CLICK + LONG_VIEW for a result the user engaged with). Use the InteractionType enum values.","examples":[["click"],["positive_feedback","click","long_view"],["negative_feedback"],["purchase","click"]]},"position":{"type":"integer","minimum":0.0,"title":"Position","description":"Position in search results where interaction occurred (0-indexed). REQUIRED. Critical for Learning to Rank - helps identify position bias. E.g., position=0 means first result, position=9 means 10th result. Higher engagement at lower positions suggests higher quality.","examples":[0,1,5,15]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.","examples":[{"device":"mobile","duration_ms":5000,"page":"search_results","viewport_position":0.75},{"interaction_reason":"not_relevant","page_number":2,"results_count":50,"search_latency_ms":150}]},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Customer's authenticated user identifier. NOT REQUIRED. Persists across sessions for long-term tracking. Enables personalization and user-specific metrics. Use your application's user ID format.","examples":["user_abc123","customer_456","usr_xyz789"]},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Temporary identifier for a single search session. NOT REQUIRED. Typically 30min-1hr duration. Tracks anonymous and authenticated users within a session. Use to group related queries and understand search journeys.","examples":["sess_abc123","session_xyz789_1234567890"]},"execution_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Id","description":"ID of the retriever execution that generated these results. NOT REQUIRED but HIGHLY RECOMMENDED for training and optimization. Links the interaction back to the exact search query, pipeline configuration, and stage execution that produced the results the user saw. Essential for: fine-tuning embeddings, training rerankers, query understanding, and tracing which pipeline configs produce better user engagement. Retrieve from the retriever execution response and pass to interactions.","examples":["exec_abc123xyz","exec_550e8400e29b41d4"]},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"ID of the retriever that was executed. NOT REQUIRED but RECOMMENDED for multi-retriever analytics. Enables comparing performance across different retriever configurations. If execution_id is provided, retriever_id can be inferred from the execution record.","examples":["ret_abc123","ret_product_search_v2"]},"query_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Query Snapshot","description":"Snapshot of the query input that generated these results. HIGHLY RECOMMENDED for training optimization. Storing the query directly enables 10-100x faster training data extraction by avoiding expensive joins to execution records. Use the same format as retriever query input (e.g., {'text': '...', 'filters': {...}}). Essential for: embedding fine-tuning (query-document pairs), query expansion learning, and analyzing which query patterns lead to better engagement. NOT REQUIRED but strongly recommended for production use cases involving model training.","examples":[{"text":"wireless headphones"},{"filters":{"price":{"lte":1000}},"text":"laptop"},{"context":"summer collection","text":"red shoes"}]},"document_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Document Score","description":"Initial retrieval score of this document when shown to the user. HIGHLY RECOMMENDED for Learning to Rank (LTR). This is a critical feature for reranker training - helps the model learn how to adjust initial scores based on user engagement. Should match the score from the retriever execution results. NOT REQUIRED but strongly recommended for LTR and reranker training.","examples":[0.95,0.87,0.62]},"result_set_size":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Result Set Size","description":"Total number of results shown to the user in this search. NOT REQUIRED but useful for context. Helps understand interaction patterns - clicking position 5 of 10 results is different from position 5 of 100 results. Useful for position bias correction and CTR analysis.","examples":[10,20,50,100]}},"type":"object","required":["feature_id","interaction_type","position"],"title":"SearchInteraction","description":"Records a user interaction with a search result.\n\nThis model captures user behavior signals that can be used to improve retrieval quality.\nEach interaction represents a user action (click, view, feedback) on a specific document\nreturned by a retriever.\n\nUse Cases:\n - Track which search results users actually click on\n - Collect explicit feedback (thumbs up/down) on result quality\n - Monitor engagement metrics (time spent viewing, sharing)\n - Identify problematic queries (zero results, immediate refinements)\n - Power Learning to Rank models with real user behavior\n\nRequirements:\n - feature_id: REQUIRED - The document/feature that was interacted with\n - interaction_type: REQUIRED - Type(s) of interaction that occurred\n - position: REQUIRED - Where in results list the interaction occurred (for LTR)\n - query_snapshot: HIGHLY RECOMMENDED - Query input for training optimization\n - document_score: HIGHLY RECOMMENDED - Initial score for LTR training\n - result_set_size: OPTIONAL - Total results shown (for context)\n - metadata: OPTIONAL - Additional context about the interaction\n - user_id: OPTIONAL - For personalization and user-specific metrics\n - session_id: OPTIONAL - For tracking multi-query sessions\n - execution_id: OPTIONAL - Link to full execution context\n - retriever_id: OPTIONAL - For multi-retriever analytics\n\nRelated Concepts:\n - Retrievers: Interactions measure retriever performance\n - Evaluations: Interactions provide real-world complement to offline evaluation\n - Learning to Rank: Interactions train ranking models","examples":[{"description":"Minimal click interaction (query_snapshot and document_score optional)","execution_id":"exec_minimal_123","feature_id":"doc_abc123","interaction_type":["click"],"position":2,"session_id":"sess_minimal"},{"description":"Simple click interaction with recommended fields for training","document_score":0.85,"feature_id":"doc_abc123","interaction_type":["click"],"position":2,"query_snapshot":{"text":"machine learning tutorials"}},{"description":"Engaged view with metadata and execution tracking","document_score":0.92,"execution_id":"exec_abc123xyz","feature_id":"prod_xyz789","interaction_type":["view","click","long_view"],"metadata":{"device":"mobile","duration_ms":12000,"viewport_position":0.85},"position":0,"query_snapshot":{"filters":{"price":{"lte":100}},"text":"wireless headphones"},"result_set_size":20,"retriever_id":"ret_product_search","session_id":"sess_abc","user_id":"user_123"},{"description":"Negative feedback","document_score":0.78,"feature_id":"doc_bad456","interaction_type":["negative_feedback","return_to_results"],"metadata":{"interaction_reason":"not_relevant"},"position":5,"query_snapshot":{"text":"python tutorial"},"result_set_size":50,"session_id":"sess_xyz"},{"description":"Purchase conversion with full tracking (high-value signal for training)","document_score":0.88,"execution_id":"exec_purchase_789","feature_id":"prod_789","interaction_type":["purchase"],"metadata":{"conversion_time_seconds":120,"purchase_amount":199.99},"position":1,"query_snapshot":{"text":"noise cancelling headphones"},"result_set_size":50,"retriever_id":"ret_product_search","session_id":"sess_purchase_001","user_id":"user_456"}]},"SearchRequest":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"Search term to match against resource names and IDs. REQUIRED. Minimum 1 character. Case-insensitive partial matching is performed. Matches against: bucket_name, bucket_id, collection_name, collection_id, retriever_name, retriever_id, taxonomy_name, taxonomy_id, cluster_name, cluster_id, namespace_name, namespace_id. Example: 'prod' matches 'production-videos', 'bkt_prod123', 'Products Collection'.","examples":["product","bkt_","video","prod"]},"resource_types":{"anyOf":[{"items":{"type":"string","enum":["bucket","collection","retriever","taxonomy","cluster","published_retriever","namespace"]},"type":"array"},{"type":"null"}],"title":"Resource Types","description":"Filter search to specific resource types. OPTIONAL - If not provided, searches all resource types. Valid values: 'bucket', 'collection', 'retriever', 'taxonomy', 'cluster', 'published_retriever', 'namespace'. Example: ['bucket', 'collection'] searches only buckets and collections.","examples":[["bucket","collection"],["retriever","published_retriever"],null]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Maximum number of results to return. OPTIONAL - Defaults to 20. Minimum: 1, Maximum: 100. Use with offset for pagination.","default":20,"examples":[20,50,100]},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of results to skip for pagination. OPTIONAL - Defaults to 0. Minimum: 0. Use with limit for pagination. Example: offset=20 with limit=20 returns results 21-40.","default":0,"examples":[0,20,40]}},"type":"object","required":["query"],"title":"SearchRequest","description":"Request model for searching across resource names and IDs.\n\nSearch is performed across all resource types within the authenticated namespace.\nThe search is case-insensitive and supports partial matching on both names and IDs.\n\nUse Cases:\n - Find resources by partial name match\n - Locate resources by ID prefix\n - Filter search to specific resource types\n - Paginate through large result sets\n\nRequirements:\n - query: REQUIRED - Search term (minimum 1 character)\n - resource_types: OPTIONAL - Filter by specific types\n - limit: OPTIONAL - Results per page (1-100, default 20)\n - offset: OPTIONAL - Pagination offset (default 0)","examples":[{"description":"Search all resources for 'product'","limit":20,"offset":0,"query":"product"},{"description":"Search only buckets and collections for 'video'","limit":50,"offset":0,"query":"video","resource_types":["bucket","collection"]},{"description":"Search by ID prefix with pagination","limit":20,"offset":20,"query":"bkt_","resource_types":["bucket"]},{"description":"Search retrievers and taxonomies","limit":10,"offset":0,"query":"recommendation","resource_types":["retriever","taxonomy"]}]},"SearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array","title":"Results","description":"List of matched resources. REQUIRED. May be empty if no matches found. Sorted by: 1) Exact matches first, 2) Partial matches, 3) Created timestamp descending. Length is min(total - offset, limit). Each result contains full resource metadata for display.","examples":[[{"created_at":"2024-01-15T10:30:00Z","description":"Product catalog","resource_id":"bkt_abc123","resource_name":"products","resource_type":"bucket"}],[]]},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of matches across all pages. REQUIRED. Count before pagination is applied. Use to calculate total pages: ceil(total / limit). May be 0 if no matches found. Example: total=50 with limit=20 means 3 pages of results.","examples":[0,15,100]},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Results per page (from request). REQUIRED. Echo of the limit parameter from the request. Range: 1-100.","examples":[20,50,100]},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Current pagination offset (from request). REQUIRED. Echo of the offset parameter from the request. Number of results skipped. Example: offset=20 means results start from the 21st match.","examples":[0,20,40]}},"type":"object","required":["results","total","limit","offset"],"title":"SearchResponse","description":"Response model for resource search results.\n\nContains paginated search results with metadata about total matches\nand pagination state. Results are sorted by relevance (exact matches first,\nthen partial matches) and creation time (newest first).\n\nUse Cases:\n - Display search results to users\n - Implement pagination UI\n - Show total result counts\n - Navigate through large result sets\n\nFields:\n - results: List of matched resources\n - total: Total number of matches (before pagination)\n - limit: Results per page (from request)\n - offset: Current pagination offset (from request)","examples":[{"description":"Successful search with multiple results","limit":20,"offset":0,"results":[{"created_at":"2024-01-15T10:30:00Z","description":"Production video content","resource_id":"bkt_prod123","resource_name":"production-videos","resource_type":"bucket","updated_at":"2024-01-20T14:22:00Z"},{"created_at":"2024-02-01T08:15:00Z","description":"Product catalog embeddings","resource_id":"col_prod456","resource_name":"Product Embeddings","resource_type":"collection"}],"total":15},{"description":"Empty search results","limit":20,"offset":0,"results":[],"total":0},{"description":"Paginated results (page 2)","limit":20,"offset":20,"results":[{"created_at":"2024-03-10T12:00:00Z","resource_id":"ret_search789","resource_name":"Search Pipeline","resource_type":"retriever","updated_at":"2024-03-15T16:45:00Z"}],"total":25}]},"SearchResultItem":{"properties":{"resource_type":{"type":"string","enum":["bucket","collection","retriever","taxonomy","cluster","published_retriever","namespace"],"title":"Resource Type","description":"Type of resource this result represents. REQUIRED. One of: 'bucket', 'collection', 'retriever', 'taxonomy', 'cluster', 'published_retriever', 'namespace'. Used to identify which resource type was matched and how to navigate to it. Example: 'bucket' indicates this is a bucket resource.","examples":["bucket","collection","retriever","taxonomy","cluster","published_retriever","namespace"]},"resource_id":{"type":"string","title":"Resource Id","description":"Unique identifier for the resource. REQUIRED. Format depends on resource_type: - bucket: 'bkt_XXXXXXXX' - collection: 'col_XXXXXXXXXX' - retriever: 'ret_XXXXXXXXXXXXXX' - taxonomy: 'tax_XXXXXXXXXXXX' - cluster: 'clust_XXXXXXXXXX' - published_retriever: 'pk_XXXXXXXXXX' - namespace: 'ns_XXXXXXXXXX'. Use this ID to fetch the full resource or perform operations on it.","examples":["bkt_abc12345","col_xyz7890123","ret_prod4567890abc","tax_categories01","clust_video0987","ns_1669d9e1ca"]},"resource_name":{"type":"string","title":"Resource Name","description":"Human-readable name of the resource. REQUIRED. This is the field that was matched in the search. Corresponds to: bucket_name, collection_name, retriever_name, taxonomy_name, cluster_name, or public_name. Example: 'Production Videos', 'Product Embeddings', 'Recommendation Engine', 'my-public-search'.","examples":["Production Videos","Product Embeddings","Recommendation Engine","Employee Taxonomy"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the resource if provided. OPTIONAL - May be null if no description was set. Provides additional context about the resource's purpose or contents.","examples":["Video content for production environment","Product catalog with CLIP embeddings",null]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the resource was created. REQUIRED. ISO 8601 format with UTC timezone. Used for sorting results by creation time."},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Timestamp when the resource was last updated. OPTIONAL - May be null if resource has never been updated. ISO 8601 format with UTC timezone."}},"type":"object","required":["resource_type","resource_id","resource_name","created_at"],"title":"SearchResultItem","description":"Individual search result representing a matched resource.\n\nContains essential metadata about the matched resource including type,\nID, name, description, and timestamps. Results are sorted by relevance\n(exact matches first) and creation time.\n\nUse Cases:\n - Display search results in UI\n - Navigate to specific resources by ID\n - Show resource metadata in search results\n - Filter or sort results client-side\n\nFields:\n - resource_type: Type of resource (bucket, collection, etc.)\n - resource_id: Unique identifier for the resource\n - resource_name: Human-readable name\n - description: Optional description text\n - created_at: When the resource was created\n - updated_at: When the resource was last updated (if applicable)","examples":[{"created_at":"2024-01-15T10:30:00Z","description":"Video content for production environment","resource_id":"bkt_abc12345","resource_name":"production-videos","resource_type":"bucket","updated_at":"2024-01-20T14:22:00Z"},{"created_at":"2024-02-01T08:15:00Z","description":"Product catalog with CLIP embeddings","resource_id":"col_xyz7890123","resource_name":"Product Embeddings","resource_type":"collection"},{"created_at":"2024-03-10T12:00:00Z","resource_id":"ret_prod4567890abc","resource_name":"Recommendation Engine","resource_type":"retriever","updated_at":"2024-03-15T16:45:00Z"}]},"SecretResponse":{"properties":{"secret_name":{"type":"string","title":"Secret Name","description":"Name of the secret that was operated on. This is the same name provided in the request. Use this name to reference the secret in api_call stage configuration.","examples":["stripe_api_key","github_token","openai_api_key"]},"created":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Created","description":"True if this secret was created, null otherwise. Only set for POST /secrets operations."},"updated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Updated","description":"True if this secret was updated, null otherwise. Only set for PUT /secrets/{name} operations."},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deleted","description":"True if this secret was deleted, null otherwise. Only set for DELETE /secrets/{name} operations."}},"type":"object","required":["secret_name"],"title":"SecretResponse","description":"Response for secret operations (NEVER includes actual decrypted value).\n\nThis response is returned after creating, updating, or deleting a secret.\nFor security, the actual secret value is NEVER included in API responses.\nOnly the secret name and operation status are returned.\n\n**Security**:\n- Decrypted secret values are NEVER included\n- Only secret name and operation status returned\n- Actual value only accessible by internal services\n\n**Fields**:\n- secret_name: Name of the secret that was operated on\n- created: True if secret was created (null for other operations)\n- updated: True if secret was updated (null for other operations)\n- deleted: True if secret was deleted (null for other operations)","examples":[{"created":true,"description":"Secret created successfully","secret_name":"stripe_api_key"},{"description":"Secret updated successfully","secret_name":"github_token","updated":true},{"deleted":true,"description":"Secret deleted successfully","secret_name":"old_api_key"}]},"SecretsListResponse":{"properties":{"secrets":{"items":{"type":"string"},"type":"array","title":"Secrets","description":"List of secret names in the organization vault. Only names are returned, never decrypted values. Use these names as references in api_call stage configuration. Names are unique within the organization. Empty list if no secrets are configured.","examples":[["stripe_api_key","github_token"],["openai_api_key"],[]]},"count":{"type":"integer","title":"Count","description":"Total number of secrets in the organization vault. This is the length of the secrets array. Useful for monitoring and auditing secret inventory.","examples":[4,1,0]}},"type":"object","required":["secrets","count"],"title":"SecretsListResponse","description":"Response for listing secrets in the organization vault.\n\nReturns ONLY secret names, never decrypted values. Use this endpoint to\ndiscover which secrets are configured in your organization.\n\n**Security**:\n- Returns ONLY secret names, never values\n- Decrypted values never exposed via API\n- Use for auditing which secrets are configured\n\n**Use Cases**:\n- Discover which secrets are configured\n- Audit secret inventory\n- Check if a secret exists before using it\n- Verify secret name spelling before referencing in api_call\n\n**Permissions**: Requires READ permission to list secrets.","examples":[{"count":4,"description":"Organization with multiple API keys configured","secrets":["stripe_api_key","github_token","openai_api_key","weather_api_key"]},{"count":1,"description":"Organization with single secret","secrets":["stripe_api_key"]},{"count":0,"description":"Organization with no secrets configured","secrets":[]}]},"SectionConfig":{"properties":{"section_id":{"type":"string","title":"Section Id","description":"Auto-generated section identifier"},"type":{"type":"string","title":"Type","description":"Section type: 'hero', 'stats-bar', 'featured-gallery', 'search-tabs', 'results-grid', 'results-list', 'markdown-content', 'iframe-embed'"},"props":{"additionalProperties":true,"type":"object","title":"Props","description":"Section-specific configuration properties"},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order","description":"Explicit render order; falls back to array position if omitted"}},"type":"object","required":["type"],"title":"SectionConfig","description":"A single section/block in a page layout."},"SendMessageRequest":{"properties":{"content":{"type":"string","minLength":1,"title":"Content","description":"Message text content (REQUIRED)"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Message metadata (OPTIONAL)"},"stream":{"type":"boolean","title":"Stream","description":"Stream response as SSE (default: True)","default":true}},"type":"object","required":["content"],"title":"SendMessageRequest","description":"Request payload for sending a message to the agent.\n\nAttributes:\n content: Message text content\n metadata: Optional message metadata\n stream: Whether to stream response as SSE (default: True)\n\nNote:\n When stream=True, the response will be Server-Sent Events (SSE).\n When stream=False, the response will be a MessageResponse object.\n\nExample:\n ```python\n # Streaming request (SSE)\n request = SendMessageRequest(\n content=\"Find videos about machine learning\",\n stream=True\n )\n\n # Non-streaming request\n request = SendMessageRequest(\n content=\"Find videos about machine learning\",\n stream=False\n )\n ```","examples":[{"content":"Find videos about machine learning","metadata":{"source":"web_app"},"stream":true}]},"SentimentClassifierParams":{"properties":{"extractor_type":{"type":"string","const":"sentiment_classifier","title":"Extractor Type","description":"Discriminator field for parameter type identification.","default":"sentiment_classifier"},"model_name":{"type":"string","title":"Model Name","description":"HuggingFace model name for sentiment classification","default":"distilbert-base-uncased-finetuned-sst-2-english"},"max_length":{"type":"integer","maximum":1024.0,"minimum":32.0,"title":"Max Length","description":"Maximum token length","default":512},"batch_size":{"type":"integer","maximum":128.0,"minimum":1.0,"title":"Batch Size","description":"Inference batch size","default":32},"return_all_scores":{"type":"boolean","title":"Return All Scores","description":"Return scores for all classes, not just top","default":true},"embed":{"type":"boolean","title":"Embed","description":"Generate E5 embeddings for semantic retrieval alongside classification. Uses the internal E5 embedding service for 1024-dimensional vectors.","default":false}},"type":"object","title":"SentimentClassifierParams","description":"Parameters for sentiment classifier."},"SessionFilter-Input":{"properties":{"retriever_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Retriever Ids","description":"Filter to sessions from these retrievers."},"taxonomy_node_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Taxonomy Node Ids","description":"Filter to sessions with these taxonomy classifications."},"time_range":{"anyOf":[{"$ref":"#/components/schemas/TimeRange-Input"},{"type":"null"}],"description":"Filter to sessions within this time window."},"min_interactions":{"type":"integer","minimum":1.0,"title":"Min Interactions","description":"Minimum number of user interactions required.","default":1},"interaction_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Interaction Types","description":"Filter to sessions with these interaction types (e.g., ['click', 'purchase'])."},"sample_strategy":{"type":"string","title":"Sample Strategy","description":"How to sample sessions: 'random', 'recent', or 'stratified'.","default":"random"},"interaction_weights":{"$ref":"#/components/schemas/InteractionWeights","description":"Custom weights for interaction types when computing relevance scores."}},"type":"object","title":"SessionFilter","description":"Criteria for selecting historical sessions to replay."},"SessionFilter-Output":{"properties":{"retriever_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Retriever Ids","description":"Filter to sessions from these retrievers."},"taxonomy_node_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Taxonomy Node Ids","description":"Filter to sessions with these taxonomy classifications."},"time_range":{"anyOf":[{"$ref":"#/components/schemas/shared__retrievers__benchmarks__models__TimeRange"},{"type":"null"}],"description":"Filter to sessions within this time window."},"min_interactions":{"type":"integer","minimum":1.0,"title":"Min Interactions","description":"Minimum number of user interactions required.","default":1},"interaction_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Interaction Types","description":"Filter to sessions with these interaction types (e.g., ['click', 'purchase'])."},"sample_strategy":{"type":"string","title":"Sample Strategy","description":"How to sample sessions: 'random', 'recent', or 'stratified'.","default":"random"},"interaction_weights":{"$ref":"#/components/schemas/InteractionWeights","description":"Custom weights for interaction types when computing relevance scores."}},"type":"object","title":"SessionFilter","description":"Criteria for selecting historical sessions to replay."},"SessionQuotas":{"properties":{"max_messages":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Messages","description":"Maximum messages allowed in session. Unset = unlimited."},"max_tokens_total":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Tokens Total","description":"Maximum cumulative tokens for session. Unset = unlimited."},"max_tool_calls":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Tool Calls","description":"Maximum tool calls per session. Unset = unlimited."},"max_session_duration_minutes":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Session Duration Minutes","description":"Maximum session lifetime in minutes. Unset = no time limit."},"rate_limit_messages_per_minute":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Rate Limit Messages Per Minute","description":"Max messages per minute to prevent spam. Unset = unlimited."}},"type":"object","title":"SessionQuotas","description":"Session-level quotas and rate limits.\n\nThese limits are enforced per-session to prevent runaway costs.\nAll fields are optional - unset means unlimited.\n\nAttributes:\n max_messages: Maximum messages allowed in session (prevents long conversations)\n max_tokens_total: Maximum cumulative tokens for session (cost control)\n max_tool_calls: Maximum tool calls per session (limits API usage)\n max_session_duration_minutes: Maximum session lifetime in minutes\n rate_limit_messages_per_minute: Max messages per minute (prevents spam)\n\nExample:\n ```python\n # Basic quotas for a demo session\n quotas = SessionQuotas(\n max_messages=50,\n max_tokens_total=50000,\n max_tool_calls=25\n )\n\n # Strict quotas for production\n quotas = SessionQuotas(\n max_messages=100,\n max_tokens_total=100000,\n max_tool_calls=50,\n max_session_duration_minutes=60,\n rate_limit_messages_per_minute=10\n )\n ```","examples":[{"max_messages":100,"max_tokens_total":100000,"max_tool_calls":50,"rate_limit_messages_per_minute":10}]},"SessionStats":{"properties":{"total_messages":{"type":"integer","minimum":0.0,"title":"Total Messages","description":"Total messages sent in session","default":0},"total_tokens":{"type":"integer","minimum":0.0,"title":"Total Tokens","description":"Cumulative tokens used (for cost tracking)","default":0},"total_tool_calls":{"type":"integer","minimum":0.0,"title":"Total Tool Calls","description":"Total tool invocations","default":0},"avg_latency_ms":{"type":"number","minimum":0.0,"title":"Avg Latency Ms","description":"Average message latency in milliseconds","default":0.0}},"type":"object","title":"SessionStats","description":"Session usage statistics.\n\nTracked in MongoDB session document, updated on each message.\nUse this to display usage metrics in your UI.\n\nAttributes:\n total_messages: Total messages sent in session\n total_tokens: Cumulative tokens used (for cost tracking)\n total_tool_calls: Total tool invocations\n avg_latency_ms: Average message latency in milliseconds\n\nExample:\n ```python\n # Display in UI\n stats = session_response.stats\n print(f\"Messages: {stats.total_messages}\")\n print(f\"Tokens used: {stats.total_tokens}\")\n print(f\"Tool calls: {stats.total_tool_calls}\")\n print(f\"Avg latency: {stats.avg_latency_ms:.0f}ms\")\n ```"},"SessionStatus":{"type":"string","enum":["active","idle","archived","terminated"],"title":"SessionStatus","description":"Session lifecycle states.\n\nAttributes:\n ACTIVE: Session is actively processing messages\n IDLE: Session exists but no recent activity\n ARCHIVED: Session archived (read-only)\n TERMINATED: Session permanently closed"},"SetupPaymentMethodResponse":{"properties":{"setup_intent_id":{"type":"string","title":"Setup Intent Id","description":"Stripe SetupIntent ID","examples":["seti_1ABC2DEF3GHI"]},"client_secret":{"type":"string","title":"Client Secret","description":"Client secret for Stripe Elements","examples":["seti_1ABC2DEF3GHI_secret_XYZ"]},"customer_id":{"type":"string","title":"Customer Id","description":"Stripe Customer ID","examples":["cus_ABC123DEF456"]}},"type":"object","required":["setup_intent_id","client_secret","customer_id"],"title":"SetupPaymentMethodResponse","description":"Response after creating a SetupIntent."},"SharePointClientCredentials":{"properties":{"type":{"type":"string","const":"client_credentials","title":"Type","default":"client_credentials"},"tenant_id":{"type":"string","title":"Tenant Id","description":"REQUIRED. Azure AD tenant ID (directory ID). Find in: Azure Portal > Azure Active Directory > Overview. Format: UUID (e.g., '12345678-1234-1234-1234-123456789abc')","examples":["12345678-1234-1234-1234-123456789abc"]},"client_id":{"type":"string","title":"Client Id","description":"REQUIRED. Azure AD application (client) ID. Find in: Azure Portal > App Registrations > Your App > Overview. Format: UUID","examples":["87654321-4321-4321-4321-cba987654321"]},"client_secret":{"type":"string","title":"Client Secret","description":"REQUIRED. Azure AD client secret for authentication. SECURITY: This field is encrypted at rest via CSFLE. Never log or expose. Generate in: Azure Portal > App Registrations > Your App > Certificates & secrets. Note: Secrets expire; consider using certificates for production."}},"type":"object","required":["tenant_id","client_id","client_secret"],"title":"SharePointClientCredentials","description":"SharePoint/OneDrive client credentials (app-only) authentication.\n\nClient credentials flow provides application-level access without user interaction.\nRecommended for automated sync operations in enterprise environments.\n\nPrerequisites:\n 1. Register an application in Azure AD (portal.azure.com)\n 2. Grant Microsoft Graph API permissions:\n - Sites.Read.All (Application) - for SharePoint site access\n - Files.Read.All (Application) - for file access\n 3. Admin consent granted for the permissions\n 4. Generate client secret\n\nSecurity:\n - client_secret encrypted at rest via CSFLE\n - Provides application-level access to all sites (based on permissions)\n - No user context - accesses files as the application itself\n - Consider using certificate-based auth for production\n\nUse Cases:\n - Automated enterprise-wide document ingestion\n - Background sync without user interaction\n - Multi-tenant applications with admin consent"},"SharePointConfig":{"properties":{"provider_type":{"type":"string","const":"sharepoint","title":"Provider Type","default":"sharepoint"},"credentials":{"oneOf":[{"$ref":"#/components/schemas/SharePointClientCredentials"},{"$ref":"#/components/schemas/SharePointDelegatedCredentials"}],"title":"Credentials","description":"REQUIRED. Azure AD authentication credentials. Choose client_credentials for production (app-only) or delegated for user-level access. The 'type' field determines which authentication flow is used.","discriminator":{"propertyName":"type","mapping":{"client_credentials":"#/components/schemas/SharePointClientCredentials","delegated":"#/components/schemas/SharePointDelegatedCredentials"}}},"site_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Id","description":"NOT REQUIRED if using personal OneDrive. SharePoint site identifier for targeting a specific site. Format: '{hostname},{site-collection-id},{web-id}' or site URL. Find via: Microsoft Graph API GET /sites?search={keyword} Example: 'contoso.sharepoint.com,12345678-...,87654321-...'","examples":["contoso.sharepoint.com,12345678-1234-1234-1234-123456789abc,87654321-4321-4321-4321-cba987654321","root"]},"drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Id","description":"NOT REQUIRED if you want to use the default document library. Specific drive (document library) ID within the site. Find via: GET /sites/{site-id}/drives Format: Base64-encoded ID starting with 'b!'","examples":["b!abc123def456..."]},"folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Path","description":"NOT REQUIRED. Path within the drive to sync from. If omitted, syncs from the root of the drive. Format: Forward-slash separated path (e.g., '/Documents/Marketing'). Note: Leading slash is optional.","examples":["/Shared Documents/Marketing","Projects/2024","/"]}},"type":"object","required":["credentials"],"title":"SharePointConfig","description":"Microsoft SharePoint and OneDrive for Business configuration.\n\nEnables Mixpeek to connect to SharePoint sites, document libraries, and\nOneDrive for Business for automated file ingestion and synchronization.\n\nArchitecture:\n SharePoint hierarchy: Tenant ā†’ Sites ā†’ Drives (Document Libraries) ā†’ Items\n - site_id: Identifies the SharePoint site\n - drive_id: Identifies a specific document library within the site\n - folder_path: Path within the document library\n\nAuthentication Methods:\n 1. Client Credentials (RECOMMENDED for production):\n - App-only access without user interaction\n - Requires admin consent for Graph API permissions\n - Access level determined by app permissions\n\n 2. Delegated:\n - User-level access via OAuth consent\n - Access limited to user's permissions\n - Requires refresh token management\n\nRequirements:\n - Azure AD application registration\n - Microsoft Graph API permissions (Sites.Read.All, Files.Read.All)\n - Network connectivity to graph.microsoft.com\n\nUse Cases:\n - Sync SharePoint document libraries\n - Ingest enterprise collaboration files\n - Monitor and process uploaded documents\n - Archive compliance-sensitive materials\n\nExample:\n ```python\n config = {\n \"provider_type\": \"sharepoint\",\n \"credentials\": {\n \"type\": \"client_credentials\",\n \"tenant_id\": \"12345678-...\",\n \"client_id\": \"87654321-...\",\n \"client_secret\": \"your-secret\",\n },\n \"site_id\": \"contoso.sharepoint.com,guid1,guid2\",\n \"drive_id\": \"b!abc123...\",\n \"folder_path\": \"/Shared Documents/Marketing\",\n }\n ```","examples":[{"credentials":{"client_id":"87654321-4321-4321-4321-cba987654321","client_secret":"your-client-secret-here","tenant_id":"12345678-1234-1234-1234-123456789abc","type":"client_credentials"},"description":"Production SharePoint with client credentials","drive_id":"b!abc123def456ghi789","folder_path":"/Shared Documents/Marketing","provider_type":"sharepoint","site_id":"contoso.sharepoint.com,12345678-1234-1234-1234-123456789abc,87654321-4321-4321-4321-cba987654321"},{"credentials":{"client_id":"87654321-4321-4321-4321-cba987654321","client_secret":"your-client-secret","refresh_token":"0.AAAA...","tenant_id":"common","type":"delegated"},"description":"Personal OneDrive with delegated auth","folder_path":"/Documents/Projects","provider_type":"sharepoint"},{"credentials":{"client_id":"87654321-4321-4321-4321-cba987654321","client_secret":"your-client-secret","tenant_id":"12345678-1234-1234-1234-123456789abc","type":"client_credentials"},"description":"SharePoint root site, default document library","provider_type":"sharepoint","site_id":"root"}]},"SharePointDelegatedCredentials":{"properties":{"type":{"type":"string","const":"delegated","title":"Type","default":"delegated"},"tenant_id":{"type":"string","title":"Tenant Id","description":"REQUIRED. Azure AD tenant ID. Use 'common' for multi-tenant apps, or specific tenant ID for single-tenant.","examples":["12345678-1234-1234-1234-123456789abc","common"]},"client_id":{"type":"string","title":"Client Id","description":"REQUIRED. Azure AD application (client) ID.","examples":["87654321-4321-4321-4321-cba987654321"]},"client_secret":{"type":"string","title":"Client Secret","description":"REQUIRED. Azure AD client secret. SECURITY: Encrypted at rest via CSFLE."},"refresh_token":{"type":"string","title":"Refresh Token","description":"REQUIRED. OAuth2 refresh token obtained from consent flow. SECURITY: Encrypted at rest. Can be revoked by user. Obtain via: Complete OAuth flow with Files.Read.All scope."}},"type":"object","required":["tenant_id","client_id","client_secret","refresh_token"],"title":"SharePointDelegatedCredentials","description":"SharePoint/OneDrive delegated (user) authentication via OAuth2.\n\nDelegated flow provides access on behalf of a specific user.\nUseful when you need to access files with user-level permissions.\n\nPrerequisites:\n 1. Register an application in Azure AD\n 2. Grant Microsoft Graph API permissions:\n - Sites.Read.All (Delegated) or Sites.Selected\n - Files.Read.All (Delegated) or Files.Read\n 3. Configure redirect URI for OAuth flow\n 4. Complete OAuth consent to obtain refresh token\n\nSecurity:\n - client_secret and refresh_token encrypted at rest\n - Access scoped to what the consenting user can access\n - Refresh tokens can be revoked by user or admin\n\nUse Cases:\n - Personal OneDrive access\n - User-specific SharePoint sites\n - Respecting per-user permissions"},"SingleLineageEntry":{"properties":{"source_config":{"$ref":"#/components/schemas/SourceConfig-Output","description":"Configuration of the source for this lineage entry"},"feature_extractor":{"$ref":"#/components/schemas/shared__collection__features__extractors__models__FeatureExtractorConfig-Output","description":"Single feature extractor applied at this stage"},"output_schema":{"$ref":"#/components/schemas/BucketSchema-Output","description":"Output schema produced by this processing stage"}},"type":"object","required":["source_config","feature_extractor","output_schema"],"title":"SingleLineageEntry","description":"Single entry in the lineage chain of a collection.\n\nEach lineage entry represents one processing stage with one feature extractor."},"SlackConfig":{"properties":{"webhook_url":{"type":"string","title":"Webhook Url","description":"Slack webhook URL"},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel","description":"Slack channel to send to"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username","description":"Username to use for the message"},"icon_emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Emoji","description":"Emoji to use as the icon"},"icon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon Url","description":"URL to an image to use as the icon"},"blocks_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocks Template","description":"Template for Slack blocks"}},"type":"object","required":["webhook_url"],"title":"SlackConfig","description":"Configuration for Slack notifications."},"SlowOperation":{"properties":{"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"When the operation occurred"},"stage_name":{"type":"string","title":"Stage Name","description":"Stage name"},"component":{"type":"string","title":"Component","description":"Component"},"latency_ms":{"type":"number","title":"Latency Ms","description":"Operation latency"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional context from profiling"}},"type":"object","required":["timestamp","stage_name","component","latency_ms"],"title":"SlowOperation","description":"Details of a slow operation."},"SlowOperationsResponse":{"properties":{"time_range":{"$ref":"#/components/schemas/api__analytics__models__TimeRange","description":"Time range of the query"},"operations":{"items":{"$ref":"#/components/schemas/SlowOperation"},"type":"array","title":"Operations","description":"List of slowest operations"},"threshold_ms":{"type":"number","title":"Threshold Ms","description":"Latency threshold used for filtering"}},"type":"object","required":["time_range","operations","threshold_ms"],"title":"SlowOperationsResponse","description":"Response for slowest operations query."},"SlowQueriesResponse":{"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"},"latency_threshold_ms":{"type":"number","title":"Latency Threshold Ms","description":"Latency threshold used"},"slow_queries":{"items":{"$ref":"#/components/schemas/SlowQueryDetails"},"type":"array","title":"Slow Queries","description":"Slow query details"},"total_slow_queries":{"type":"integer","title":"Total Slow Queries","description":"Total slow queries found"}},"type":"object","required":["namespace_id","time_range_days","latency_threshold_ms","slow_queries","total_slow_queries"],"title":"SlowQueriesResponse","description":"Response for slow queries endpoint."},"SlowQueryDetails":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Retriever that executed the query"},"query":{"type":"string","title":"Query","description":"Query input string"},"latency_ms":{"type":"number","title":"Latency Ms","description":"Query latency in milliseconds"},"results_count":{"type":"integer","title":"Results Count","description":"Number of results returned"},"queried_fields":{"items":{"type":"string"},"type":"array","title":"Queried Fields","description":"List of metadata fields queried"}},"type":"object","required":["retriever_id","query","latency_ms","results_count","queried_fields"],"title":"SlowQueryDetails","description":"Details of a slow query."},"SnowflakeConfig":{"properties":{"provider_type":{"type":"string","const":"snowflake","title":"Provider Type","default":"snowflake"},"credentials":{"oneOf":[{"$ref":"#/components/schemas/SnowflakeKeyPairCredentials"},{"$ref":"#/components/schemas/SnowflakeUsernamePasswordCredentials"}],"title":"Credentials","description":"REQUIRED. Authentication credentials for Snowflake. Choose key_pair for production (recommended) or username_password for simpler setup. The 'type' field determines which credential mechanism is used.","discriminator":{"propertyName":"type","mapping":{"key_pair":"#/components/schemas/SnowflakeKeyPairCredentials","username_password":"#/components/schemas/SnowflakeUsernamePasswordCredentials"}}},"account":{"type":"string","title":"Account","description":"REQUIRED. Snowflake account identifier. Format: {account_locator}.{cloud_region} or {org_name}-{account_name} Find in: Snowflake UI > Account dropdown > Account URL","examples":["xy12345.us-east-1","myorg-prod","acme-analytics"]},"warehouse":{"type":"string","title":"Warehouse","description":"REQUIRED. Warehouse name for compute resources. Must have USAGE privilege on this warehouse. Warehouse will be used for all sync queries. Consider: Use dedicated warehouse for sync operations to isolate costs.","examples":["COMPUTE_WH","MIXPEEK_SYNC_WH","ETL_SMALL"]},"database":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Database","description":"NOT REQUIRED if fully qualified table name used in source_path. Database name for default context. Can be omitted if source_path uses {DATABASE}.{SCHEMA}.{TABLE} format. Must have USAGE privilege if specified.","examples":["PRODUCTION","ANALYTICS_DB","CUSTOMER_DATA"]},"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema","description":"NOT REQUIRED if fully qualified table name used in source_path. Schema name for default context. Can be omitted if source_path uses {SCHEMA}.{TABLE} or {DATABASE}.{SCHEMA}.{TABLE}. Must have USAGE privilege if specified.","examples":["PUBLIC","RAW_DATA","TRANSFORMED"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"NOT REQUIRED. Snowflake role to use for operations. If omitted, uses user's default role. Role must have SELECT on target tables and USAGE on database/schema/warehouse. Best practice: Create dedicated read-only role for sync operations.","examples":["MIXPEEK_SYNC_ROLE","READ_ONLY","DATA_ENGINEER"]},"incremental_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incremental Column","description":"NOT REQUIRED. Column name for incremental sync watermark. Should be a TIMESTAMP, TIMESTAMP_NTZ, or DATE column that tracks row modifications. When set, only rows with {incremental_column} > last_sync_watermark are synced. Common values: updated_at, modified_at, last_updated, ingestion_timestamp. If omitted, full table scan on every sync (not recommended for large tables).","examples":["updated_at","modified_at","last_updated","ingestion_timestamp"]},"primary_key_columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Primary Key Columns","description":"NOT REQUIRED. Column names forming the primary key for stable object IDs. Used to generate deterministic file_id for deduplication. If omitted, uses hash of entire row content (less stable). Recommendation: Always specify for production to ensure idempotent syncs.","examples":[["id"],["user_id","timestamp"],["customer_id","order_id"]]},"query_timeout_seconds":{"type":"integer","maximum":3600.0,"minimum":30.0,"title":"Query Timeout Seconds","description":"Query timeout in seconds. Prevents long-running queries from blocking sync operations. Default: 300 seconds (5 minutes). Increase for large tables or complex queries.","default":300},"fetch_size":{"type":"integer","maximum":10000.0,"minimum":100.0,"title":"Fetch Size","description":"Number of rows to fetch per network round-trip. Higher values reduce network overhead but increase memory usage. Default: 1000 rows. Tune based on row size and available memory.","default":1000}},"type":"object","required":["credentials","account","warehouse"],"title":"SnowflakeConfig","description":"Snowflake data warehouse configuration for table-based sync.\n\nEnables syncing Snowflake table rows as JSON objects in Mixpeek buckets.\nEach row becomes one object, with incremental sync via watermark columns.\n\nAuthentication Options:\n - Key Pair: Recommended for production (secure, password-less)\n - Username/Password: Fallback option (simpler setup)\n\nRequirements:\n - Snowflake account with read access to target tables\n - Warehouse with compute resources\n - SELECT permissions on target tables/schemas\n - USAGE permissions on database, schema, warehouse\n\nUse Cases:\n - Sync customer data tables for AI/ML pipelines\n - Ingest product catalog for search/recommendations\n - Process transaction logs for analytics\n - Mirror metadata tables for vector search\n\nExample:\n Production setup with key pair auth:\n ```python\n config = {\n \"provider_type\": \"snowflake\",\n \"credentials\": {\n \"type\": \"key_pair\",\n \"username\": \"MIXPEEK_SYNC\",\n \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\n },\n \"account\": \"xy12345.us-east-1\",\n \"warehouse\": \"MIXPEEK_SYNC_WH\",\n \"database\": \"PRODUCTION\",\n \"schema\": \"PUBLIC\",\n \"role\": \"SYNC_ROLE\",\n \"incremental_column\": \"updated_at\",\n \"primary_key_columns\": [\"id\"],\n }\n ```","examples":[{"account":"xy12345.us-east-1","credentials":{"private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","type":"key_pair","username":"MIXPEEK_SYNC"},"database":"PRODUCTION","description":"Production setup with key pair auth and incremental sync","incremental_column":"updated_at","primary_key_columns":["id"],"provider_type":"snowflake","role":"MIXPEEK_SYNC_ROLE","schema":"PUBLIC","warehouse":"MIXPEEK_SYNC_WH"},{"account":"myorg-analytics","credentials":{"password":"secure_password_here","type":"username_password","username":"SYNC_USER"},"database":"ANALYTICS","description":"Simple username/password setup","incremental_column":"modified_at","primary_key_columns":["customer_id","event_id"],"provider_type":"snowflake","schema":"RAW","warehouse":"COMPUTE_WH"}]},"SnowflakeKeyPairCredentials":{"properties":{"type":{"type":"string","const":"key_pair","title":"Type","default":"key_pair"},"username":{"type":"string","title":"Username","description":"Snowflake username for authentication","examples":["MIXPEEK_SYNC_USER","data_ingestion"]},"private_key":{"type":"string","title":"Private Key","description":"REQUIRED. PEM-encoded RSA private key for authentication. SECURITY: This field is encrypted at rest via CSFLE. Never log or expose. Format: -----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY----- "},"private_key_passphrase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Private Key Passphrase","description":"NOT REQUIRED. Passphrase for encrypted private key. SECURITY: Encrypted at rest if provided. Use only if private key is passphrase-protected."}},"type":"object","required":["username","private_key"],"title":"SnowflakeKeyPairCredentials","description":"Snowflake key pair authentication (RECOMMENDED for production).\n\nKey pair authentication provides secure, password-less access to Snowflake.\nThe private key is encrypted at rest using MongoDB CSFLE.\n\nPrerequisites:\n 1. Generate RSA key pair (2048-bit minimum)\n 2. Extract public key and assign to Snowflake user\n 3. Store private key securely (encrypted)\n\nSecurity:\n - Private key encrypted at rest via CSFLE\n - No password exposure\n - Key rotation supported\n - Recommended for production\n\nExample:\n Generate key pair:\n ```bash\n openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt\n openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub\n ```\n\n Assign public key to Snowflake user:\n ```sql\n ALTER USER mixpeek_sync SET RSA_PUBLIC_KEY='MIIBIjANBg...';\n ```"},"SnowflakeUsernamePasswordCredentials":{"properties":{"type":{"type":"string","const":"username_password","title":"Type","default":"username_password"},"username":{"type":"string","title":"Username","description":"REQUIRED. Snowflake username (case-insensitive).","examples":["MIXPEEK_SYNC_USER","data_ingestion"]},"password":{"type":"string","title":"Password","description":"REQUIRED. Snowflake password for authentication. SECURITY: This field is encrypted at rest via CSFLE. Never log or expose."}},"type":"object","required":["username","password"],"title":"SnowflakeUsernamePasswordCredentials","description":"Snowflake username/password authentication (FALLBACK option).\n\nTraditional username/password authentication for Snowflake.\nLess secure than key pair authentication but simpler to set up.\n\nSecurity:\n - Password encrypted at rest via CSFLE\n - Consider using key pair auth for production\n - Enable MFA on Snowflake user account"},"SortDirection":{"type":"string","enum":["asc","desc"],"title":"SortDirection","description":"Sort direction options."},"SortOption":{"properties":{"field":{"type":"string","title":"Field","description":"Field to sort by, supports dot notation for nested fields","example":"created_at"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction","default":"asc","example":"desc"}},"type":"object","required":["field"],"title":"SortOption","description":"Specifies how to sort query results.\n\nAttributes:\n field: Field to sort by\n direction: Sort direction (ascending or descending)"},"SourceCollection-Input":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"The ID of the source collection for the taxonomy."},"enrichment_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/EnrichmentField"},"type":"array"},{"type":"null"}],"title":"Enrichment Fields","description":"Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied."}},"type":"object","required":["collection_id"],"title":"SourceCollection","description":"A source collection for a flat taxonomy.","examples":[{"collection_id":"col_products_v1","enrichment_fields":[{"field_path":"metadata.tags","merge_mode":"append"}],"input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"retriever_id":"ret_clip_v1"}]},"SourceCollection-Output":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"The ID of the source collection for the taxonomy."},"enrichment_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/EnrichmentField"},"type":"array"},{"type":"null"}],"title":"Enrichment Fields","description":"Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied."}},"type":"object","required":["collection_id"],"title":"SourceCollection","description":"A source collection for a flat taxonomy.","examples":[{"collection_id":"col_products_v1","enrichment_fields":[{"field_path":"metadata.tags","merge_mode":"append"}],"input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"retriever_id":"ret_clip_v1"}]},"SourceConfig-Input":{"properties":{"type":{"$ref":"#/components/schemas/SourceType","description":"REQUIRED. Type of source for this collection. 'bucket': Process objects from one or more buckets (first-stage processing). 'collection': Process documents from another collection (downstream processing). Use 'bucket' for initial data ingestion, 'collection' for decomposition trees.","examples":["bucket","collection"]},"bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Bucket Ids","description":"List of bucket IDs when type='bucket'. REQUIRED when type='bucket'. NOT ALLOWED when type='collection'. Can specify one or more buckets to process. Single bucket: Use array with one element ['bkt_id']. Multiple buckets: All buckets MUST have compatible schemas. Schema compatibility validated at collection creation. Compatible schemas have: 1) Same field names, 2) Same field types, 3) Same required status. Documents will include root_bucket_id to track which bucket they came from. Use cases: multi-region data, multi-team consolidation, environment aggregation.","examples":[["bkt_marketing_videos"],["bkt_us_products","bkt_eu_products","bkt_asia_products"],["bkt_staging_data","bkt_production_data"]]},"source_namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Namespace Id","description":"Namespace ID where the source buckets reside. Use this to process buckets from a different namespace within the same organization. When omitted, buckets are looked up in the current (collection's) namespace. Only valid when type='bucket'."},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID when type='collection' (single collection). Use this OR collection_ids (not both). REQUIRED when type='collection' and processing single collection. NOT ALLOWED when type='bucket'. The collection will process documents from this upstream collection. The upstream collection's output_schema becomes this collection's input_schema. This enables decomposition trees (multi-stage pipelines). Example: Process frames collection ā†’ create scenes collection.","examples":["col_video_frames","col_book_chapters","col_product_images"]},"collection_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Collection Ids","description":"List of collection IDs when type='collection' (multiple collections). Use this OR collection_id (not both). REQUIRED when type='collection' and processing multiple collections. NOT ALLOWED when type='bucket'. Used for operations that consolidate multiple upstream collections. Example: Clustering across multiple collections ā†’ cluster output collection. All collections must have compatible schemas for consolidation operations.","examples":[["col_us_products","col_eu_products"],["col_images_2023","col_images_2024"]]},"inherited_bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inherited Bucket Ids","description":"List of original bucket IDs that source collections originated from. OPTIONAL. Only used when type='collection'. Tracks the complete lineage chain: buckets ā†’ collections ā†’ derived collections. Extracted from upstream collection metadata at collection creation time. Enables tracing derived collections (like cluster outputs) back to original data sources. Example: Cluster output collection inherits bucket IDs from its source collections. Format: List of bucket IDs with 'bkt_' prefix.","examples":[["bkt_marketing_videos"],["bkt_us_products","bkt_eu_products"],null]},"source_filters":{"anyOf":[{"$ref":"#/components/schemas/SourceFilters-Input"},{"type":"null"}],"description":"Optional filters to apply to source data. When specified, only objects/documents matching these filters will be processed by this collection. Filters are evaluated at batch creation time. Uses same LogicalOperator model as list APIs for consistency.","examples":[{"filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},{"filters":{"AND":[{"field":"metadata.status","operator":"eq","value":"active"}]}},{}]}},"type":"object","required":["type"],"title":"SourceConfig","description":"Configuration for collection source (bucket(s) or collection).\n\nCollections can process data from two types of sources:\n\n1. **Bucket Source**: Process raw objects from one or more buckets (first-stage processing)\n - Use this to create your initial collections from uploaded data\n - Can specify multiple buckets to consolidate data from different sources\n - All buckets must have compatible schemas (validated at creation)\n - Example: Videos from multiple regions ā†’ Frame extraction collection\n\n2. **Collection Source**: Process documents from another collection (decomposition trees)\n - Use this to create multi-stage processing pipelines\n - Example: Frames collection ā†’ Scene detection collection\n\nMulti-Bucket Requirements:\n- All buckets must have compatible schemas (same fields, types, and required status)\n- Schema compatibility is validated when the collection is created\n- Documents track which specific bucket they came from via root_bucket_id\n- Useful for consolidating data from multiple regions, teams, or environments\n\nThe source determines:\n- What data the feature extractor receives as input\n- The input_schema available for input_mappings and field_passthrough\n- The lineage tracking in output documents\n\nExamples:\n Single bucket: {\"type\": \"bucket\", \"bucket_ids\": [\"bkt_products\"]}\n Multi-bucket: {\"type\": \"bucket\", \"bucket_ids\": [\"bkt_us\", \"bkt_eu\", \"bkt_asia\"]}\n Collection: {\"type\": \"collection\", \"collection_id\": \"col_frames\"}","examples":[{"bucket_ids":["bkt_marketing_videos"],"description":"Single bucket source","type":"bucket"},{"bucket_ids":["bkt_marketing_ads"],"description":"Bucket source with video-only filter","source_filters":{"filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},"type":"bucket"},{"bucket_ids":["bkt_us_products","bkt_eu_products","bkt_asia_products"],"description":"Multi-bucket source (region consolidation)","type":"bucket"},{"bucket_ids":["bkt_us_ads","bkt_eu_ads","bkt_asia_ads"],"description":"Multi-bucket source with brand filter","source_filters":{"filters":{"OR":[{"field":"brand_name","operator":"in","value":["Acme","TechCo"]},{"field":"category","operator":"eq","value":"premium"}]}},"type":"bucket"},{"collection_id":"col_video_frames","description":"Collection source (decomposition tree)","type":"collection"},{"collection_id":"col_raw_frames","description":"Collection source with active documents only","source_filters":{"filters":{"AND":[{"field":"__fully_enriched","operator":"eq","value":true},{"field":"quality_score","operator":"gte","value":0.8}]}},"type":"collection"},{"collection_ids":["col_us_products","col_eu_products","col_asia_products"],"description":"Multi-collection source (cluster output)","type":"collection"}]},"SourceConfig-Output":{"properties":{"type":{"$ref":"#/components/schemas/SourceType","description":"REQUIRED. Type of source for this collection. 'bucket': Process objects from one or more buckets (first-stage processing). 'collection': Process documents from another collection (downstream processing). Use 'bucket' for initial data ingestion, 'collection' for decomposition trees.","examples":["bucket","collection"]},"bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Bucket Ids","description":"List of bucket IDs when type='bucket'. REQUIRED when type='bucket'. NOT ALLOWED when type='collection'. Can specify one or more buckets to process. Single bucket: Use array with one element ['bkt_id']. Multiple buckets: All buckets MUST have compatible schemas. Schema compatibility validated at collection creation. Compatible schemas have: 1) Same field names, 2) Same field types, 3) Same required status. Documents will include root_bucket_id to track which bucket they came from. Use cases: multi-region data, multi-team consolidation, environment aggregation.","examples":[["bkt_marketing_videos"],["bkt_us_products","bkt_eu_products","bkt_asia_products"],["bkt_staging_data","bkt_production_data"]]},"source_namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Namespace Id","description":"Namespace ID where the source buckets reside. Use this to process buckets from a different namespace within the same organization. When omitted, buckets are looked up in the current (collection's) namespace. Only valid when type='bucket'."},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID when type='collection' (single collection). Use this OR collection_ids (not both). REQUIRED when type='collection' and processing single collection. NOT ALLOWED when type='bucket'. The collection will process documents from this upstream collection. The upstream collection's output_schema becomes this collection's input_schema. This enables decomposition trees (multi-stage pipelines). Example: Process frames collection ā†’ create scenes collection.","examples":["col_video_frames","col_book_chapters","col_product_images"]},"collection_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Collection Ids","description":"List of collection IDs when type='collection' (multiple collections). Use this OR collection_id (not both). REQUIRED when type='collection' and processing multiple collections. NOT ALLOWED when type='bucket'. Used for operations that consolidate multiple upstream collections. Example: Clustering across multiple collections ā†’ cluster output collection. All collections must have compatible schemas for consolidation operations.","examples":[["col_us_products","col_eu_products"],["col_images_2023","col_images_2024"]]},"inherited_bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Inherited Bucket Ids","description":"List of original bucket IDs that source collections originated from. OPTIONAL. Only used when type='collection'. Tracks the complete lineage chain: buckets ā†’ collections ā†’ derived collections. Extracted from upstream collection metadata at collection creation time. Enables tracing derived collections (like cluster outputs) back to original data sources. Example: Cluster output collection inherits bucket IDs from its source collections. Format: List of bucket IDs with 'bkt_' prefix.","examples":[["bkt_marketing_videos"],["bkt_us_products","bkt_eu_products"],null]},"source_filters":{"anyOf":[{"$ref":"#/components/schemas/SourceFilters-Output"},{"type":"null"}],"description":"Optional filters to apply to source data. When specified, only objects/documents matching these filters will be processed by this collection. Filters are evaluated at batch creation time. Uses same LogicalOperator model as list APIs for consistency.","examples":[{"filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},{"filters":{"AND":[{"field":"metadata.status","operator":"eq","value":"active"}]}},{}]}},"type":"object","required":["type"],"title":"SourceConfig","description":"Configuration for collection source (bucket(s) or collection).\n\nCollections can process data from two types of sources:\n\n1. **Bucket Source**: Process raw objects from one or more buckets (first-stage processing)\n - Use this to create your initial collections from uploaded data\n - Can specify multiple buckets to consolidate data from different sources\n - All buckets must have compatible schemas (validated at creation)\n - Example: Videos from multiple regions ā†’ Frame extraction collection\n\n2. **Collection Source**: Process documents from another collection (decomposition trees)\n - Use this to create multi-stage processing pipelines\n - Example: Frames collection ā†’ Scene detection collection\n\nMulti-Bucket Requirements:\n- All buckets must have compatible schemas (same fields, types, and required status)\n- Schema compatibility is validated when the collection is created\n- Documents track which specific bucket they came from via root_bucket_id\n- Useful for consolidating data from multiple regions, teams, or environments\n\nThe source determines:\n- What data the feature extractor receives as input\n- The input_schema available for input_mappings and field_passthrough\n- The lineage tracking in output documents\n\nExamples:\n Single bucket: {\"type\": \"bucket\", \"bucket_ids\": [\"bkt_products\"]}\n Multi-bucket: {\"type\": \"bucket\", \"bucket_ids\": [\"bkt_us\", \"bkt_eu\", \"bkt_asia\"]}\n Collection: {\"type\": \"collection\", \"collection_id\": \"col_frames\"}","examples":[{"bucket_ids":["bkt_marketing_videos"],"description":"Single bucket source","type":"bucket"},{"bucket_ids":["bkt_marketing_ads"],"description":"Bucket source with video-only filter","source_filters":{"filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},"type":"bucket"},{"bucket_ids":["bkt_us_products","bkt_eu_products","bkt_asia_products"],"description":"Multi-bucket source (region consolidation)","type":"bucket"},{"bucket_ids":["bkt_us_ads","bkt_eu_ads","bkt_asia_ads"],"description":"Multi-bucket source with brand filter","source_filters":{"filters":{"OR":[{"field":"brand_name","operator":"in","value":["Acme","TechCo"]},{"field":"category","operator":"eq","value":"premium"}]}},"type":"bucket"},{"collection_id":"col_video_frames","description":"Collection source (decomposition tree)","type":"collection"},{"collection_id":"col_raw_frames","description":"Collection source with active documents only","source_filters":{"filters":{"AND":[{"field":"__fully_enriched","operator":"eq","value":true},{"field":"quality_score","operator":"gte","value":0.8}]}},"type":"collection"},{"collection_ids":["col_us_products","col_eu_products","col_asia_products"],"description":"Multi-collection source (cluster output)","type":"collection"}]},"SourceDetails":{"properties":{"type":{"$ref":"#/components/schemas/SourceType","description":"Immediate origin type from which this entity was derived."},"source_id":{"type":"string","title":"Source Id","description":"Identifier of the immediate source entity (e.g., bucket_id, collection_id, taxonomy_id)."}},"type":"object","required":["type","source_id"],"title":"SourceDetails","description":"Generic source details for any Qdrant point/document.\n\nKeep this intentionally minimal so specialized models (e.g., DocumentSourceDetails)\ncan extend it with domain-specific fields."},"SourceEnrichmentConfig":{"properties":{"field_mappings":{"items":{"$ref":"#/components/schemas/EnrichmentFieldMapping"},"type":"array","title":"Field Mappings","description":"List of field mappings from cluster results to document fields. Default includes cluster_id and cluster_label. Can include: distance_to_centroid, member_count, keywords, visualization coords (x, y, z), etc."}},"type":"object","title":"SourceEnrichmentConfig","description":"Configuration for enriching source collection documents with cluster assignments.\n\nWhen enrich_source_collection=True, cluster assignments are written back to\nthe original source documents, similar to taxonomy enrichment.\n\nUses flexible field mapping pattern to support any cluster result fields.","examples":[{"field_mappings":[{"source_field":"cluster_id","target_field":"category_id"},{"source_field":"cluster_label","target_field":"category_name"},{"source_field":"distance_to_centroid","target_field":"category_confidence"}]},{"field_mappings":[{"source_field":"cluster_id","target_field":"segment"},{"source_field":"cluster_label","target_field":"segment_label"},{"source_field":"x","target_field":"viz_x"},{"source_field":"y","target_field":"viz_y"}]}]},"SourceFilters-Input":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Optional logical filters to apply to source data. Uses LogicalOperator model with AND/OR/NOT support. When specified, only objects/documents matching these filters will be processed by this collection. When null, all source data is processed (no filtering). Filters are consistent across all batch runs for this collection.","examples":[{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]},{"AND":[{"field":"metadata.status","operator":"eq","value":"active"},{"field":"created_at","operator":"gte","value":"2025-10-01T00:00:00Z"}]},{"OR":[{"field":"brand_name","operator":"in","value":["Acme","TechCo"]},{"field":"category","operator":"eq","value":"premium"}]}]}},"type":"object","title":"SourceFilters","description":"Filters applied to source data when processing collections.\n\nSource filters determine which objects (from buckets) or documents (from collections)\nare processed by this collection. Filters use the same LogicalOperator model as\nlist APIs throughout the system, supporting complex AND/OR/NOT logic.\n\nUse Cases:\n - Process only specific content types from mixed-content buckets\n - Filter by metadata fields (status, category, tags, dates)\n - Create specialized collections from broader sources\n - Exclude certain objects or documents from processing\n\nExamples:\n Process only video content:\n {\n \"AND\": [\n {\"field\": \"blobs.type\", \"operator\": \"eq\", \"value\": \"video\"}\n ]\n }\n\n Process only active, published content:\n {\n \"AND\": [\n {\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"active\"},\n {\"field\": \"metadata.published\", \"operator\": \"eq\", \"value\": true}\n ]\n }\n\n Process content from last 30 days:\n {\n \"AND\": [\n {\"field\": \"created_at\", \"operator\": \"gte\", \"value\": \"2025-10-08T00:00:00Z\"}\n ]\n }\n\n Process specific brands OR categories:\n {\n \"OR\": [\n {\"field\": \"brand_name\", \"operator\": \"in\", \"value\": [\"Acme\", \"TechCo\"]},\n {\"field\": \"category\", \"operator\": \"eq\", \"value\": \"premium\"}\n ]\n }\n\nFilter Operators:\n - eq (equals)\n - ne (not equals)\n - gt (greater than)\n - gte (greater than or equal)\n - lt (less than)\n - lte (less than or equal)\n - in (value in list)\n - nin (value not in list)\n - contains (string contains)\n - starts_with (string starts with)\n - ends_with (string ends with)\n\nPerformance Considerations:\n - Filters are evaluated at batch creation time\n - Only matching objects/documents are included in processing\n - More selective filters = smaller batches = faster processing\n - Use indexed fields (metadata, timestamps) for better performance\n\nRelationship to Batch Filters:\n - Source filters: Applied at collection definition (consistent across all batches)\n - Batch filters: Applied at batch creation (ad-hoc, per-batch basis)\n - Both can be used together: source filters + batch filters = intersection","examples":[{"description":"Filter only video content","filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},{"description":"Filter active content from specific brands","filters":{"AND":[{"field":"metadata.status","operator":"eq","value":"active"},{"field":"brand_name","operator":"in","value":["Acme","TechCo","Innovate"]}]}},{"description":"Filter by content type and date range","filters":{"AND":[{"OR":[{"field":"blobs.type","operator":"eq","value":"video"},{"field":"blobs.type","operator":"eq","value":"image"}]},{"field":"created_at","operator":"gte","value":"2025-10-01T00:00:00Z"},{"field":"created_at","operator":"lte","value":"2025-10-31T23:59:59Z"}]}},{"description":"No filters - process all source data"}]},"SourceFilters-Output":{"properties":{"filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"type":"null"}],"description":"Optional logical filters to apply to source data. Uses LogicalOperator model with AND/OR/NOT support. When specified, only objects/documents matching these filters will be processed by this collection. When null, all source data is processed (no filtering). Filters are consistent across all batch runs for this collection.","examples":[{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]},{"AND":[{"field":"metadata.status","operator":"eq","value":"active"},{"field":"created_at","operator":"gte","value":"2025-10-01T00:00:00Z"}]},{"OR":[{"field":"brand_name","operator":"in","value":["Acme","TechCo"]},{"field":"category","operator":"eq","value":"premium"}]}]}},"type":"object","title":"SourceFilters","description":"Filters applied to source data when processing collections.\n\nSource filters determine which objects (from buckets) or documents (from collections)\nare processed by this collection. Filters use the same LogicalOperator model as\nlist APIs throughout the system, supporting complex AND/OR/NOT logic.\n\nUse Cases:\n - Process only specific content types from mixed-content buckets\n - Filter by metadata fields (status, category, tags, dates)\n - Create specialized collections from broader sources\n - Exclude certain objects or documents from processing\n\nExamples:\n Process only video content:\n {\n \"AND\": [\n {\"field\": \"blobs.type\", \"operator\": \"eq\", \"value\": \"video\"}\n ]\n }\n\n Process only active, published content:\n {\n \"AND\": [\n {\"field\": \"metadata.status\", \"operator\": \"eq\", \"value\": \"active\"},\n {\"field\": \"metadata.published\", \"operator\": \"eq\", \"value\": true}\n ]\n }\n\n Process content from last 30 days:\n {\n \"AND\": [\n {\"field\": \"created_at\", \"operator\": \"gte\", \"value\": \"2025-10-08T00:00:00Z\"}\n ]\n }\n\n Process specific brands OR categories:\n {\n \"OR\": [\n {\"field\": \"brand_name\", \"operator\": \"in\", \"value\": [\"Acme\", \"TechCo\"]},\n {\"field\": \"category\", \"operator\": \"eq\", \"value\": \"premium\"}\n ]\n }\n\nFilter Operators:\n - eq (equals)\n - ne (not equals)\n - gt (greater than)\n - gte (greater than or equal)\n - lt (less than)\n - lte (less than or equal)\n - in (value in list)\n - nin (value not in list)\n - contains (string contains)\n - starts_with (string starts with)\n - ends_with (string ends with)\n\nPerformance Considerations:\n - Filters are evaluated at batch creation time\n - Only matching objects/documents are included in processing\n - More selective filters = smaller batches = faster processing\n - Use indexed fields (metadata, timestamps) for better performance\n\nRelationship to Batch Filters:\n - Source filters: Applied at collection definition (consistent across all batches)\n - Batch filters: Applied at batch creation (ad-hoc, per-batch basis)\n - Both can be used together: source filters + batch filters = intersection","examples":[{"description":"Filter only video content","filters":{"AND":[{"field":"blobs.type","operator":"eq","value":"video"}]}},{"description":"Filter active content from specific brands","filters":{"AND":[{"field":"metadata.status","operator":"eq","value":"active"},{"field":"brand_name","operator":"in","value":["Acme","TechCo","Innovate"]}]}},{"description":"Filter by content type and date range","filters":{"AND":[{"OR":[{"field":"blobs.type","operator":"eq","value":"video"},{"field":"blobs.type","operator":"eq","value":"image"}]},{"field":"created_at","operator":"gte","value":"2025-10-01T00:00:00Z"},{"field":"created_at","operator":"lte","value":"2025-10-31T23:59:59Z"}]}},{"description":"No filters - process all source data"}]},"SourceType":{"type":"string","enum":["bucket","collection","taxonomy","cluster"],"title":"SourceType","description":"Generic source types for any Qdrant point/document."},"SparseVector":{"properties":{"indices":{"items":{"anyOf":[{"type":"integer"},{"type":"number"}]},"type":"array","title":"Indices","description":"Indices of non-zero elements"},"values":{"items":{"type":"number"},"type":"array","title":"Values","description":"Values of non-zero elements"}},"type":"object","required":["indices","values"],"title":"SparseVector","description":"Sparse vector representation with indices and values.\n\nOnly non-zero elements are stored for efficiency.\n\nExample:\n```json\n{\n \"indices\": [0, 2, 4],\n \"values\": [0.1, 0.3, 0.5]\n}\n```"},"SpectralParams":{"properties":{"n_clusters":{"type":"integer","minimum":2.0,"title":"N Clusters","description":"Number of clusters to form","default":8},"eigen_solver":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eigen Solver","description":"The eigenvalue decomposition strategy ('arpack', 'lobpcg', 'amg', or None)"},"n_components":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"N Components","description":"Number of eigenvectors to use for spectral embedding"},"random_state":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Random State","description":"Random seed for reproducibility","default":42},"n_init":{"type":"integer","minimum":1.0,"title":"N Init","description":"Number of times k-means will run with different centroid seeds","default":10},"gamma":{"type":"number","exclusiveMinimum":0.0,"title":"Gamma","description":"Kernel coefficient for rbf, poly, sigmoid, laplacian and chi2 kernels","default":1.0},"affinity":{"type":"string","title":"Affinity","description":"How to construct the affinity matrix ('nearest_neighbors', 'rbf', 'precomputed', 'precomputed_nearest_neighbors')","default":"rbf"},"n_neighbors":{"type":"integer","minimum":1.0,"title":"N Neighbors","description":"Number of neighbors to use when constructing the affinity matrix using nearest neighbors","default":10},"eigen_tol":{"type":"number","minimum":0.0,"title":"Eigen Tol","description":"Stopping criterion for eigendecomposition","default":0.0},"assign_labels":{"type":"string","title":"Assign Labels","description":"Strategy to assign labels in the embedding space ('kmeans' or 'discretize')","default":"kmeans"},"degree":{"type":"number","title":"Degree","description":"Degree of the polynomial kernel. Ignored by other kernels","default":3},"coef0":{"type":"number","title":"Coef0","description":"Zero coefficient for polynomial and sigmoid kernels","default":1},"kernel_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Kernel Params","description":"Parameters for the kernel function"},"n_jobs":{"type":"integer","title":"N Jobs","description":"Number of parallel jobs to run (-1 means using all processors)","default":1},"verbose":{"type":"boolean","title":"Verbose","description":"Verbosity mode","default":false}},"type":"object","title":"SpectralParams","description":"Parameters for Spectral clustering algorithm."},"SpendingCapsResponse":{"properties":{"monthly_spending_budget":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Spending Budget","description":"Soft spending limit in USD cents (null = unlimited)","examples":[10000,50000,100000]},"monthly_spending_budget_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Spending Budget Usd","description":"Soft spending limit in USD","examples":[100.0,500.0,1000.0]},"spending_alert_thresholds":{"items":{"type":"integer"},"type":"array","title":"Spending Alert Thresholds","description":"Percentage thresholds for spending alerts","examples":[[50,75,90,100]]},"spending_alerts_enabled":{"type":"boolean","title":"Spending Alerts Enabled","description":"Whether spending alerts are enabled","default":true},"spending_alerts_sent":{"items":{"type":"integer"},"type":"array","title":"Spending Alerts Sent","description":"Alert thresholds triggered in current billing cycle","examples":[[50,75]]},"hard_spending_cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Hard Spending Cap","description":"Hard spending limit in USD cents (null = no hard cap)","examples":[50000,100000,500000]},"hard_spending_cap_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Hard Spending Cap Usd","description":"Hard spending limit in USD","examples":[500.0,1000.0,5000.0]},"hard_cap_enabled":{"type":"boolean","title":"Hard Cap Enabled","description":"Whether hard spending cap is enforced","default":false},"current_spending_cents":{"type":"integer","title":"Current Spending Cents","description":"Current spending in current billing cycle (cents)","examples":[23450]},"current_spending_usd":{"type":"number","title":"Current Spending Usd","description":"Current spending in current billing cycle (USD)","examples":[234.5]},"budget_percentage_used":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Budget Percentage Used","description":"Percentage of budget used (null if no budget set)","examples":[46.9,78.2]}},"type":"object","required":["current_spending_cents","current_spending_usd"],"title":"SpendingCapsResponse","description":"Response with spending cap configuration."},"SplitMethod":{"type":"string","enum":["time","scene","silence"],"title":"SplitMethod","description":"Split methods for video extraction."},"StageBreakdownResponse":{"properties":{"retriever_id":{"type":"string","title":"Retriever Id","description":"Retriever identifier"},"stages":{"items":{"$ref":"#/components/schemas/StagePerformanceMetrics"},"type":"array","title":"Stages","description":"Stage metrics"},"total_latency_ms":{"type":"number","title":"Total Latency Ms","description":"Total pipeline latency"}},"type":"object","required":["retriever_id","stages","total_latency_ms"],"title":"StageBreakdownResponse","description":"Stage breakdown response.","examples":[{"retriever_id":"ret_abc123","stages":[{"avg_documents_in":0,"avg_documents_out":100,"avg_latency_ms":45.3,"execution_count":1234,"p95_latency_ms":89.2,"stage_name":"knn_search","stage_type":"vector_search"},{"avg_documents_in":100,"avg_documents_out":10,"avg_latency_ms":102.5,"execution_count":1234,"p95_latency_ms":198.7,"stage_name":"rerank","stage_type":"reranking"}],"total_latency_ms":147.8}]},"StageCategory":{"type":"string","enum":["filter","sort","reduce","apply","enrich"],"title":"StageCategory","description":"Retriever stage categories organized by transformation pattern.\n\nValues:\n FILTER: Subset of input documents (N ā†’ ā‰¤N, same schema)\n - Removes documents that don't match criteria\n - Examples: attribute_filter, feature_filter, llm_filter\n - Use for: Removing irrelevant results, applying business rules\n - Performance: Fast (attribute) to slow (LLM)\n\n SORT: Reorders documents (N ā†’ N, same schema, different order)\n - Changes document ordering based on criteria\n - Examples: sort_relevance, sort_attribute\n - Use for: Ordering by relevance, recency, custom fields\n - Performance: Fast (in-memory sort)\n\n REDUCE: Aggregates to summary (N ā†’ 1, new schema)\n - Combines multiple documents into one summary\n - Examples: aggregate_stats, group_by\n - Use for: Summaries, statistics, reports\n - Performance: Varies by aggregation logic\n\n APPLY: Enrichment or expansion (N ā†’ N or N*M)\n - 1-1: Enriches each doc (N ā†’ N, expanded schema)\n - 1-N: Expands each doc (N ā†’ N*M, new/same schema)\n - Examples: document_enrich, taxonomy_enrich, llm_enrich\n - Use for: Adding related data, tagging, recursive lookups\n - Performance: Moderate (DB) to slow (LLM)\n\n ENRICH: Document enrichment (N ā†’ N, potentially expanded schema)\n - Adds computed fields to each document\n - Examples: code_execution, llm_enrich, taxonomy_enrich\n - Use for: Custom transformations, data extraction, LLM processing\n - Performance: Varies (fast for code, slow for LLM)\n\nPipeline Patterns:\n - Basic: FILTER ā†’ SORT\n - Enriched: FILTER ā†’ SORT ā†’ APPLY\n - Tag expansion: FILTER ā†’ APPLY (1-N)\n - Summary: FILTER ā†’ SORT ā†’ REDUCE"},"StageConfig":{"properties":{"stage_name":{"type":"string","minLength":1,"title":"Stage Name","description":"Human-readable stage instance name (REQUIRED)."},"stage_type":{"anyOf":[{"$ref":"#/components/schemas/StageType"},{"type":"null"}],"description":"Functional category of the stage. Optional for creation requests; auto-inferred from `stage_id` when omitted."},"config":{"additionalProperties":true,"type":"object","title":"Config","description":"Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields."},"batch_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Size","description":"Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"User-facing description of the stage (OPTIONAL)."},"on_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"On Error","description":"Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images)."},"output_alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Alias","description":"Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT. in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets)."}},"type":"object","required":["stage_name","config"],"title":"StageConfig","description":"Configuration for a single stage within a retriever.\n\nStages support dynamic configuration through template expressions using Jinja2 syntax.\n\nIMPORTANT - Template Syntax:\n - Use DOUBLE curly braces: {{INPUT.query}} (correct)\n - Single curly braces will NOT work: {INPUT.query} (wrong - not substituted)\n - Namespace names are CASE-INSENSITIVE: {{INPUT.query}}, {{inputs.query}}, {{input.query}}\n all work identically\n\nTemplate Namespaces (case-insensitive):\n - INPUT / inputs / input: User-provided query parameters and inputs\n - DOC / doc: Current document fields (for per-document logic)\n - CONTEXT / context: Execution state (budget, timing, retriever metadata)\n - STAGE / stage: Previous stage outputs (for cascading logic)\n\nExamples:\n Correct: {{INPUT.query_text}}, {{inputs.query}}, {{DOC.content_type}}\n Correct: {{CONTEXT.budget_remaining}}, {{context.budget_remaining}}\n Wrong: {INPUT.query} - single braces won't be substituted","examples":[{"config":{"parameters":{"final_top_k":25,"searches":[{"feature_uri":"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1","query":{"input_mode":"text","value":"{{INPUT.query_text}}"},"top_k":100}]},"stage_id":"feature_search"},"description":"Feature search stage with uppercase template namespace","stage_name":"semantic_search","stage_type":"filter"},{"batch_size":"{{20 * inputs.page_size}}","config":{"parameters":{"field":"metadata.price","operator":"gt","value":"{{inputs.min_price}}"},"stage_id":"attribute_filter"},"description":"Attribute filter with lowercase template namespace","stage_name":"price_filter","stage_type":"filter"},{"config":{"parameters":{"batch_size":"{{CONTEXT.budget_remaining > 50 ? 200 : 50}}","criteria":"{{inputs.quality_criteria}}","field":"{{DOC.media_type == 'image' ? 'image_url' : 'video_url'}}"},"stage_id":"llm_filter"},"description":"Mixed case templates in same stage","stage_name":"llm_filter","stage_type":"filter"},{"config":{"parameters":{"final_top_k":10,"searches":[{"feature_uri":"mixpeek://web_scraper@v1/jinaai__jina_embeddings_v2_base_code","query":{"input_mode":"text","value":"{{INPUT.query}}"},"top_k":50}]},"pre_filters":{"AND":[{"field":"doc_type","operator":"eq","value":"code"}]},"stage_id":"feature_search"},"description":"Feature search with pre_filters (sibling of parameters, NOT inside)","stage_name":"search_code_blocks","stage_type":"filter"}]},"StageDiscovery":{"properties":{"stage_id":{"type":"string","title":"Stage Id","description":"Unique identifier for the stage"},"description":{"type":"string","title":"Description","description":"Human-readable description of stage behavior"},"category":{"type":"string","title":"Category","description":"Transformation category: filter, sort, reduce, apply, enrich"},"icon":{"type":"string","title":"Icon","description":"Lucide React icon identifier"},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema","description":"JSON Schema for stage parameters"},"example_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Example Config","description":"Example stage configuration"},"common_use_cases":{"items":{"type":"string"},"type":"array","title":"Common Use Cases","description":"Common scenarios where this stage is useful"},"cost_tier":{"type":"string","title":"Cost Tier","description":"Relative cost tier: cheap, moderate, expensive","default":"moderate"},"requires_collections":{"type":"boolean","title":"Requires Collections","description":"Whether this stage requires collection access","default":true}},"type":"object","required":["stage_id","description","category","icon"],"title":"StageDiscovery","description":"Extended stage discovery information with examples.\n\nIncludes everything from RetrieverStageDefinition plus\nusage examples and common patterns.","examples":[{"category":"filter","common_use_cases":["Semantic search over embeddings","Multi-modal retrieval","Hybrid search with fusion"],"cost_tier":"moderate","description":"Unified multi-vector search with N feature URIs and fusion","example_config":{"parameters":{"feature_uri":"multimodal_extractor.v1.embedding","query":"{{ INPUT.query }}","top_k":25},"stage_id":"feature_filter","stage_name":"semantic_search"},"icon":"search","parameter_schema":{"properties":{"feature_uri":{"type":"string"},"top_k":{"default":25,"type":"integer"}},"type":"object"},"requires_collections":true,"stage_id":"feature_filter"}]},"StageInstanceConfig":{"properties":{"stage_name":{"type":"string","title":"Stage Name"},"stage_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage Id","description":"Stage implementation ID (overrides stage_name for lookups)"},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Stage parameters"},"pre_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply to the documents *before* this stage is executed.These filters are combined with any global retriever filters."},"post_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Filters to apply to the documents *after* this stage is executed.These filters are applied to the results of this stage before passing to the next."},"stats":{"anyOf":[{"$ref":"#/components/schemas/StagePerformance-Input"},{"type":"null"}],"description":"Performance statistics for this stage"}},"type":"object","required":["stage_name"],"title":"StageInstanceConfig","description":"User-provided configuration for a stage instance in a retriever pipeline.\n\nThis model is used when creating a retriever to define the specific\nparameters for each stage."},"StagePerformance-Input":{"properties":{"avg_execution_ms":{"type":"number","title":"Avg Execution Ms","description":"Average execution time in milliseconds","default":0.0},"execution_count":{"type":"integer","title":"Execution Count","description":"Number of times executed","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Number of errors encountered","default":0},"last_executed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Executed At","description":"Last time this stage was executed"}},"type":"object","title":"StagePerformance","description":"Performance statistics for a retriever stage."},"StagePerformance-Output":{"properties":{"stage_name":{"type":"string","title":"Stage Name","description":"Name of the profiled stage"},"component":{"type":"string","title":"Component","description":"Component (e.g., extractor, cluster)"},"execution_count":{"type":"integer","title":"Execution Count","description":"Number of executions"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"max_latency_ms":{"type":"number","title":"Max Latency Ms","description":"Maximum latency"},"total_time_ms":{"type":"number","title":"Total Time Ms","description":"Total time spent in this stage"},"pct_of_total":{"type":"number","title":"Pct Of Total","description":"Percentage of total time spent in this stage"}},"type":"object","required":["stage_name","component","execution_count","avg_latency_ms","p95_latency_ms","max_latency_ms","total_time_ms","pct_of_total"],"title":"StagePerformance","description":"Performance breakdown by stage."},"StagePerformanceMetrics":{"properties":{"stage_name":{"type":"string","title":"Stage Name","description":"Name of the stage"},"stage_type":{"type":"string","title":"Stage Type","description":"Type of the stage"},"execution_count":{"type":"integer","title":"Execution Count","description":"Number of executions"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"P95 latency"},"avg_documents_in":{"type":"number","title":"Avg Documents In","description":"Average documents input"},"avg_documents_out":{"type":"number","title":"Avg Documents Out","description":"Average documents output"}},"type":"object","required":["stage_name","stage_type","execution_count","avg_latency_ms","p95_latency_ms","avg_documents_in","avg_documents_out"],"title":"StagePerformanceMetrics","description":"Stage-level performance metrics."},"StageProgress":{"properties":{"stage":{"$ref":"#/components/schemas/MigrationStage","description":"Stage name"},"status":{"$ref":"#/components/schemas/MigrationStatus","description":"Stage status"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"Stage start time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Stage completion time"},"progress_percent":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Progress Percent","description":"Progress %","default":0.0},"items_total":{"type":"integer","minimum":0.0,"title":"Items Total","description":"Total items to process","default":0},"items_completed":{"type":"integer","minimum":0.0,"title":"Items Completed","description":"Items completed","default":0},"items_failed":{"type":"integer","minimum":0.0,"title":"Items Failed","description":"Items failed","default":0},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error if failed"}},"type":"object","required":["stage","status"],"title":"StageProgress","description":"Progress tracking for a migration stage."},"StageStatistics":{"properties":{"input_count":{"type":"integer","minimum":0.0,"title":"Input Count","description":"Number of documents received by the stage (REQUIRED)."},"output_count":{"type":"integer","minimum":0.0,"title":"Output Count","description":"Number of documents emitted by the stage (REQUIRED)."},"duration_ms":{"type":"number","minimum":0.0,"title":"Duration Ms","description":"Wall-clock duration in milliseconds (REQUIRED)."},"efficiency":{"type":"number","minimum":0.0,"title":"Efficiency","description":"Output/Input ratio. 0 when input_count is 0 (REQUIRED)."},"cache_hit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cache Hit","description":"Indicates whether the result originated from stage cache (OPTIONAL)."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Stage-specific error message if execution failed but retriever execution continued (OPTIONAL)."},"llm_calls":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Llm Calls","description":"Number of LLM invocations performed by the stage (OPTIONAL)."},"tokens_used":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Tokens Used","description":"Total tokens consumed by the stage (OPTIONAL, only for LLM stages)."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Stage-specific metadata containing additional execution details (OPTIONAL). For example, join stages include: join_strategy, join_type, matched_count, match_rate, etc. LLM stages may include: model_name, temperature, max_tokens, etc."}},"type":"object","required":["input_count","output_count","duration_ms","efficiency"],"title":"StageStatistics","description":"Execution metrics for a single stage in a retriever execution run.","examples":[{"cache_hit":false,"duration_ms":123.4,"efficiency":0.05,"input_count":5000,"output_count":250}]},"StageType":{"type":"string","enum":["filter","sort","reduce","apply","enrich"],"title":"StageType","description":"Categorisation of stage behaviour within a retrieval flow.\n\nThese functional categories describe how stages transform the document stream:\n\n- FILTER: N ā†’ ā‰¤N documents (subset, same schema)\n- SORT: N ā†’ N documents (same docs, different order, same schema)\n- REDUCE: N ā†’ 1 document (aggregation, new schema)\n- APPLY: N ā†’ N or N*M documents (enrichment/expansion, expanded/new schema)\n- ENRICH: N ā†’ N documents (enrichment with computed fields)"},"StartEvaluationRequest":{"properties":{"dataset_name":{"type":"string","minLength":1,"title":"Dataset Name","description":"Name of the evaluation dataset to use"},"evaluation_config":{"anyOf":[{"$ref":"#/components/schemas/EvaluationConfig"},{"type":"null"}],"description":"Optional evaluation configuration (uses defaults if not provided)"}},"type":"object","required":["dataset_name"],"title":"StartEvaluationRequest","description":"Request to start an evaluation."},"StartEvaluationResponse":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Task ID for tracking progress"},"evaluation_id":{"type":"string","title":"Evaluation Id","description":"Evaluation ID"},"task_type":{"type":"string","title":"Task Type","description":"Task type","default":"retriever.evaluation"},"status":{"type":"string","title":"Status","description":"Initial status","default":"pending"},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp"}},"type":"object","required":["task_id","evaluation_id","created_at"],"title":"StartEvaluationResponse","description":"Response when starting an evaluation."},"StartMigrationRequest":{"properties":{"force":{"type":"boolean","title":"Force","description":"Force start even if validation warnings exist","default":false}},"type":"object","title":"StartMigrationRequest","description":"Request to start a migration."},"StartMigrationResponse":{"properties":{"migration_id":{"type":"string","title":"Migration Id","description":"Migration ID"},"status":{"$ref":"#/components/schemas/MigrationStatus","description":"Current status"},"task_id":{"type":"string","title":"Task Id","description":"Celery task ID"},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"Start timestamp"},"message":{"type":"string","title":"Message","description":"Human-readable message"}},"type":"object","required":["migration_id","status","task_id","started_at","message"],"title":"StartMigrationResponse","description":"Response after starting a migration.","example":{"message":"Migration started successfully. Track progress at GET /migrations/{id}","migration_id":"mig_abc123xyz789","started_at":"2025-12-03T10:05:00Z","status":"pending","task_id":"task_xyz789"}},"StatItem":{"properties":{"label":{"type":"string","title":"Label","description":"Stat label (e.g. 'Total Ads')"},"value":{"type":"string","title":"Value","description":"Stat value (e.g. '12,400+')"}},"type":"object","required":["label","value"],"title":"StatItem","description":"A single stat item for the stats bar."},"StepAnalyticsConfig-Input":{"properties":{"timestamp_field":{"type":"string","title":"Timestamp Field","description":"Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')","examples":["Date","metadata.timestamp","created_at"]},"sequence_id_field":{"type":"string","title":"Sequence Id Field","description":"Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')","examples":["Thread-Index","metadata.session_id","user_id"]},"step_key_source":{"$ref":"#/components/schemas/StepKeySource","description":"How to determine the 'step' for each document (label, node_id, or custom field)","default":"assignment_label"},"step_key_field_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step Key Field Path","description":"Required if step_key_source='field_path'. Dot-notation path to step value in document.","examples":["metadata.workflow_stage","status","enrichments.stage"]},"covariates":{"items":{"$ref":"#/components/schemas/CovariateConfig"},"type":"array","maxItems":20,"title":"Covariates","description":"Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)"},"max_sequence_duration_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Max Sequence Duration Days","description":"Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues."}},"type":"object","required":["timestamp_field","sequence_id_field"],"title":"StepAnalyticsConfig","description":"Configuration for step-by-step transition analytics on taxonomy assignments.\n\nEnables analysis of how documents progress through taxonomy labels as a temporal\nsequence, answering questions like:\n- How long from \"inquiry\" to \"closed_won\"?\n- What % of \"inquiry\" emails reach \"proposal\"?\n- Which sender domains correlate with faster progression?\n\nUse Cases:\n 1. Email Thread Analysis:\n - Track progression: inquiry ā†’ followup ā†’ proposal ā†’ closed_won\n - Identify which subject lines correlate with faster closure\n\n 2. Content Workflow Tracking:\n - Monitor: draft ā†’ review ā†’ approved ā†’ published\n - Find bottlenecks and optimization opportunities\n\n 3. Safety Compliance Monitoring:\n - Trace: violation_detected ā†’ investigated ā†’ resolved\n - Track resolution times and success rates\n\nAttributes:\n timestamp_field: Document field containing event timestamp\n sequence_id_field: Field that groups related documents into sequences\n step_key_source: How to extract the step identifier (label/node_id/custom field)\n step_key_field_path: Required if step_key_source='field_path'\n covariates: List of predictor variables to analyze for conversion lift\n max_sequence_duration_days: Filter out sequences longer than this (data quality)\n\nExample:\n ```python\n # Email thread analysis configuration\n StepAnalyticsConfig(\n timestamp_field=\"Date\", # Email timestamp\n sequence_id_field=\"Thread-Index\", # Groups emails in same thread\n step_key_source=\"assignment_label\", # Use taxonomy label as step\n covariates=[\n CovariateConfig(\n field_path=\"sender_domain\",\n covariate_type=\"categorical\",\n name=\"Sender Domain\"\n ),\n CovariateConfig(\n field_path=\"word_count\",\n covariate_type=\"numeric\",\n name=\"Email Length\"\n )\n ],\n max_sequence_duration_days=90 # Ignore threads >90 days\n )\n ```"},"StepAnalyticsConfig-Output":{"properties":{"timestamp_field":{"type":"string","title":"Timestamp Field","description":"Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')","examples":["Date","metadata.timestamp","created_at"]},"sequence_id_field":{"type":"string","title":"Sequence Id Field","description":"Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')","examples":["Thread-Index","metadata.session_id","user_id"]},"step_key_source":{"$ref":"#/components/schemas/StepKeySource","description":"How to determine the 'step' for each document (label, node_id, or custom field)","default":"assignment_label"},"step_key_field_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step Key Field Path","description":"Required if step_key_source='field_path'. Dot-notation path to step value in document.","examples":["metadata.workflow_stage","status","enrichments.stage"]},"covariates":{"items":{"$ref":"#/components/schemas/CovariateConfig"},"type":"array","maxItems":20,"title":"Covariates","description":"Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)"},"max_sequence_duration_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Max Sequence Duration Days","description":"Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues."}},"type":"object","required":["timestamp_field","sequence_id_field"],"title":"StepAnalyticsConfig","description":"Configuration for step-by-step transition analytics on taxonomy assignments.\n\nEnables analysis of how documents progress through taxonomy labels as a temporal\nsequence, answering questions like:\n- How long from \"inquiry\" to \"closed_won\"?\n- What % of \"inquiry\" emails reach \"proposal\"?\n- Which sender domains correlate with faster progression?\n\nUse Cases:\n 1. Email Thread Analysis:\n - Track progression: inquiry ā†’ followup ā†’ proposal ā†’ closed_won\n - Identify which subject lines correlate with faster closure\n\n 2. Content Workflow Tracking:\n - Monitor: draft ā†’ review ā†’ approved ā†’ published\n - Find bottlenecks and optimization opportunities\n\n 3. Safety Compliance Monitoring:\n - Trace: violation_detected ā†’ investigated ā†’ resolved\n - Track resolution times and success rates\n\nAttributes:\n timestamp_field: Document field containing event timestamp\n sequence_id_field: Field that groups related documents into sequences\n step_key_source: How to extract the step identifier (label/node_id/custom field)\n step_key_field_path: Required if step_key_source='field_path'\n covariates: List of predictor variables to analyze for conversion lift\n max_sequence_duration_days: Filter out sequences longer than this (data quality)\n\nExample:\n ```python\n # Email thread analysis configuration\n StepAnalyticsConfig(\n timestamp_field=\"Date\", # Email timestamp\n sequence_id_field=\"Thread-Index\", # Groups emails in same thread\n step_key_source=\"assignment_label\", # Use taxonomy label as step\n covariates=[\n CovariateConfig(\n field_path=\"sender_domain\",\n covariate_type=\"categorical\",\n name=\"Sender Domain\"\n ),\n CovariateConfig(\n field_path=\"word_count\",\n covariate_type=\"numeric\",\n name=\"Email Length\"\n )\n ],\n max_sequence_duration_days=90 # Ignore threads >90 days\n )\n ```"},"StepInfo":{"properties":{"step_key":{"type":"string","title":"Step Key","description":"Step identifier"},"event_count":{"type":"integer","minimum":0.0,"title":"Event Count","description":"Total events for this step"},"sequence_count":{"type":"integer","minimum":0.0,"title":"Sequence Count","description":"Unique sequences with this step"},"first_seen":{"type":"string","title":"First Seen","description":"Earliest event timestamp (ISO format)"},"last_seen":{"type":"string","title":"Last Seen","description":"Most recent event timestamp (ISO format)"}},"type":"object","required":["step_key","event_count","sequence_count","first_seen","last_seen"],"title":"StepInfo","description":"Information about a single step in the taxonomy analytics data.\n\nAttributes:\n step_key: The step identifier (e.g., \"inquiry\", \"closed_won\")\n event_count: Number of events with this step\n sequence_count: Number of unique sequences with this step\n first_seen: ISO timestamp of earliest event with this step\n last_seen: ISO timestamp of most recent event with this step"},"StepKeySource":{"type":"string","enum":["assignment_label","assignment_node_id","field_path"],"title":"StepKeySource","description":"Defines how to extract the step key from documents for sequence analysis.\n\nThe step key identifies which stage/state a document is in for transition analytics.\n\nExamples:\n ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., \"inquiry\", \"proposal\")\n ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., \"node_sales_inquiry\")\n FIELD_PATH: Use a custom document field (e.g., \"metadata.workflow_stage\")"},"StepTransitionRequest":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"Collection to analyze for step transitions"},"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"Taxonomy ID (each taxonomy_id is immutable, clone creates new ID)"},"from_step":{"type":"string","title":"From Step","description":"Starting step label (e.g., 'inquiry', 'draft')","examples":["inquiry","draft","violation_detected"]},"to_step":{"type":"string","title":"To Step","description":"Ending step label (e.g., 'closed_won', 'published')","examples":["closed_won","published","resolved"]},"max_window_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Max Window Days","description":"Maximum days between from_step and to_step. Sequences exceeding this are excluded."},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters","description":"Optional filters for events (e.g., {'metadata.region': 'US'})"},"override_step_analytics":{"anyOf":[{"$ref":"#/components/schemas/StepAnalyticsConfig-Input"},{"type":"null"}],"description":"Override taxonomy's default step_analytics config for this query"},"min_support":{"type":"integer","minimum":1.0,"title":"Min Support","description":"Minimum number of sequences required for valid analysis","default":10}},"type":"object","required":["collection_id","taxonomy_id","from_step","to_step"],"title":"StepTransitionRequest","description":"API request model for step transition analytics.\n\nThis model extends the engine query model with API-specific validation\nand documentation.\n\nUse this to analyze how documents transition from one taxonomy step to another,\ncomputing conversion rates, durations, and predictor lifts.\n\nExample:\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\nResponse includes:\n - Conversion rate (% reaching to_step)\n - Duration statistics (mean, median, p90, p95)\n - Top predictors (covariates with highest lift)"},"StepTransitionResponse":{"properties":{"from_step":{"type":"string","title":"From Step","description":"Starting step"},"to_step":{"type":"string","title":"To Step","description":"Ending step"},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of sequences starting at from_step"},"converted":{"type":"integer","minimum":0.0,"title":"Converted","description":"Number of sequences that reached to_step"},"conversion_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Conversion Rate","description":"Percentage that converted (converted / count)"},"durations_sec":{"anyOf":[{"$ref":"#/components/schemas/DurationStats"},{"type":"null"}],"description":"Duration statistics (None if no conversions)"},"top_predictors":{"items":{"$ref":"#/components/schemas/PredictorLift"},"type":"array","maxItems":50,"title":"Top Predictors","description":"Covariates with highest lift (sorted by absolute lift)"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional metadata (collection_id, event counts, etc.)"}},"type":"object","required":["from_step","to_step","count","converted","conversion_rate"],"title":"StepTransitionResponse","description":"API response model for step transition analytics.\n\nContains comprehensive statistics about the Aā†’B transition including\nconversion metrics, duration analysis, and predictor insights.\n\nExample Response:\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 \"std_dev\": 172800.0,\n \"min\": 86400.0,\n \"max\": 1209600.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 \"metadata\": {\n \"collection_id\": \"col_emails\",\n \"taxonomy_id\": \"tax_sales_stages\",\n \"total_events_analyzed\": 5432\n }\n }\n ```"},"StorageConnectionCreateRequest":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"REQUIRED. Human-readable name for the storage connection. Must be unique within the organization. Displayed in dashboards and sync logs. Format: 1-100 characters, descriptive of the connection's purpose.","examples":["Marketing Google Drive","Production S3 Bucket","Customer Assets Archive"]},"provider_type":{"$ref":"#/components/schemas/StorageProvider","description":"REQUIRED. Storage provider to connect to. Supported providers: google_drive, s3, snowflake, sharepoint, tigris. Determines which authentication and sync logic is used.","examples":["google_drive","s3","snowflake","sharepoint","tigris"]},"provider_config":{"additionalProperties":true,"type":"object","title":"Provider Config","description":"REQUIRED. Provider-specific configuration including credentials. Structure varies by provider_type. SECURITY: Sensitive credential fields (private_key, secret_access_key, client_secret, refresh_token, session_token) are automatically encrypted at rest and never appear in responses or logs.","examples":[{"credentials":{"client_email":"sync@project.iam.gserviceaccount.com","type":"service_account"},"description":"Google Drive configuration","shared_drive_id":"0AH-Xabc123"},{"bucket":"my-bucket","credentials":{"access_key_id":"AKIA...","secret_access_key":"***REDACTED***"},"description":"S3 configuration","region":"us-east-1"}]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"OPTIONAL. Description explaining the connection's purpose and scope. Helpful for team collaboration and documentation. Format: Up to 500 characters.","examples":["Shared drive for marketing team assets and campaign materials","Production S3 bucket containing customer-uploaded videos"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"OPTIONAL. Arbitrary key-value metadata for tagging and categorization. Common uses: team tags, cost center codes, project identifiers.","examples":[{"cost_center":"CC-1234","team":"marketing"},{"environment":"production","project":"q4-campaign"}]},"test_before_save":{"type":"boolean","title":"Test Before Save","description":"OPTIONAL. Whether to validate credentials before saving the connection. Defaults to True. If True, connection will be tested against the provider before creation. If False, connection is saved without validation (use with caution).","default":true}},"type":"object","required":["name","provider_type","provider_config"],"title":"StorageConnectionCreateRequest","description":"Request payload for creating a new storage connection.\n\nUse this to connect Mixpeek to external storage providers like Google Drive\nor S3. The connection will be tested before being saved (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- Credentials are encrypted at rest using MongoDB field-level encryption\n- Credentials never appear in API responses or logs\n- Connection is tested before saving to validate credentials\n\n**Examples:**\n```python\n# Google Drive connection\n{\n \"name\": \"Marketing Drive\",\n \"provider_type\": \"google_drive\",\n \"provider_config\": {\n \"credentials\": {...},\n \"shared_drive_id\": \"0AH-Xabc123\"\n },\n \"description\": \"Team drive for marketing assets\"\n}\n```","examples":[{"description":"Team drive for marketing assets","name":"Marketing Google Drive","provider_config":{"credentials":{"client_email":"sync@project.iam.gserviceaccount.com","type":"service_account"},"shared_drive_id":"0AH-Xabc123"},"provider_type":"google_drive","test_before_save":true},{"metadata":{"environment":"production"},"name":"Production S3 Bucket","provider_config":{"bucket":"my-bucket","credentials":{"access_key_id":"AKIA..."},"region":"us-east-1"},"provider_type":"s3","test_before_save":false}]},"StorageConnectionListResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/StorageConnectionModel"},"type":"array","title":"Results","description":"List of storage connections matching the request filters. Results are paginated according to the pagination parameters. SECURITY: Sensitive credential fields are automatically redacted."},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination metadata including total count, page number, page size, and navigation links for next/previous pages."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of connections matching the filters (before pagination). Use this to calculate total pages and display pagination controls.","examples":[0,5,42]}},"type":"object","required":["results","pagination","total"],"title":"StorageConnectionListResponse","description":"Response envelope for listing storage connections.\n\nContains paginated results and metadata about the listing operation.","examples":[{"description":"Paginated list response","pagination":{"page":1,"page_size":10,"total":10,"total_pages":1},"results":[{"connection_id":"conn_abc123","is_active":true,"name":"Marketing Drive","provider_type":"google_drive","status":"active"}],"total":10}]},"StorageConnectionModel":{"properties":{"connection_id":{"type":"string","title":"Connection Id","description":"Unique identifier for the storage connection. Auto-generated with 'conn_' prefix followed by secure random token. Format: conn_{15-character alphanumeric}. Used for API operations and audit trails.","examples":["conn_abc123def456ghi","conn_xyz789uvw012qrs"]},"internal_id":{"type":"string","title":"Internal Id","description":"REQUIRED. Organization internal identifier for multi-tenancy scoping. All connection operations are scoped to this organization. Format: int_{24-character secure token}.","examples":["int_org123abc456def789xyz012"]},"provider_type":{"$ref":"#/components/schemas/StorageProvider","description":"REQUIRED. Storage provider implementation to use. Determines which client adapter is loaded for sync operations. Supported: google_drive, s3, snowflake, sharepoint, tigris."},"provider_config":{"anyOf":[{"$ref":"#/components/schemas/GoogleDriveConfig"},{"$ref":"#/components/schemas/S3Config"},{"$ref":"#/components/schemas/SnowflakeConfig"},{"$ref":"#/components/schemas/SharePointConfig"},{"$ref":"#/components/schemas/TigrisConfig"},{"$ref":"#/components/schemas/PostgreSQLConfig"},{"$ref":"#/components/schemas/InstagramConfig"},{"$ref":"#/components/schemas/TikTokConfig"},{"$ref":"#/components/schemas/RSSConfig"},{"$ref":"#/components/schemas/HTTPAPIConfig"},{"$ref":"#/components/schemas/BoxConfig"},{"additionalProperties":true,"type":"object"}],"title":"Provider Config","description":"REQUIRED. Provider-specific configuration payload including credentials. Type depends on provider_type (GoogleDriveConfig, S3Config, etc.). SECURITY: Sensitive credential fields are encrypted at rest via MongoDB client-side field level encryption (CSFLE). Credentials never appear in API responses or logs. See provider_configs.py for detailed schemas."},"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"REQUIRED. Human-readable connection name for identification. Displayed in dashboards, sync logs, and API responses. Must be unique within the organization for clarity. Format: 1-100 characters, descriptive of the connection's purpose.","examples":["Marketing Google Drive","Production S3 Bucket","Customer Assets Archive"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"NOT REQUIRED. Optional description explaining the connection's purpose and scope. Helpful for team collaboration and documentation. Format: Up to 500 characters.","examples":["Shared drive for marketing team assets and campaign materials","Production S3 bucket containing customer-uploaded videos"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"Operational status of the connection. ACTIVE: Connection is healthy and ready for use in sync operations. SUSPENDED: Temporarily disabled by user, credentials preserved but sync paused. FAILED: Health checks failing, credentials may be invalid or expired. ARCHIVED: Permanently retired, cannot be reactivated. Status transitions automatically based on health checks and user actions.","default":"ACTIVE"},"is_active":{"type":"boolean","title":"Is Active","description":"Quick boolean flag for filtering active connections in queries. True when status is ACTIVE, False for SUSPENDED/FAILED/ARCHIVED. Maintained automatically when status changes. Use for efficient filtering: db.connections.find({'is_active': True})","default":true},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"NOT REQUIRED. UTC timestamp of the most recent successful sync operation. Updated automatically after each successful file sync/list operation. None if connection has never been used. Useful for identifying stale connections and usage analytics."},"last_error":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Last Error","description":"NOT REQUIRED. Most recent error message from failed health check or sync. Populated when authentication fails, network errors occur, or permissions denied. None when connection is healthy. Format: Error message truncated to 1000 characters. Used for diagnostics and troubleshooting.","examples":["Authentication failed: Invalid credentials","Permission denied: Unable to access shared drive","Network timeout: Failed to connect to storage.googleapis.com"]},"consecutive_failures":{"type":"integer","minimum":0.0,"title":"Consecutive Failures","description":"Counter tracking consecutive failed health checks or sync attempts. Incremented on each failure, reset to 0 on success. Used to implement automatic connection suspension. Auto-suspend after 5 consecutive failures to prevent account lockout. Range: 0 to infinity (typically 0-10).","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC timestamp when the connection was created. Auto-generated using shared.utilities.helpers.current_time(). Immutable after creation. Format: ISO 8601 datetime."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"UTC timestamp of the most recent update to the connection. Updated automatically on any field modification. Tracks configuration changes, status updates, and credential refreshes. Format: ISO 8601 datetime."},"created_by_user_id":{"type":"string","title":"Created By User Id","description":"REQUIRED. User identifier of the user who created this connection. Used for audit trails and permission checks. Format: usr_{15-character alphanumeric}. Immutable after creation.","examples":["usr_34bbf6ded1b749"]},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary key-value metadata provided by the user. Useful for tagging, categorization, and custom annotations. NOT REQUIRED - defaults to empty dictionary. Common uses: team tags, cost center codes, project identifiers.","examples":[{"cost_center":"CC-1234","team":"marketing"},{"environment":"production","project":"q4-campaign"},{"tags":["customer-facing","high-priority"]}]}},"type":"object","required":["internal_id","provider_type","provider_config","name","created_by_user_id"],"title":"StorageConnectionModel","description":"Canonical representation of an external storage provider connection.\n\nStorage connections enable Mixpeek to access external cloud storage providers\n(Google Drive, S3, etc.) for automated file ingestion and synchronization.\nEach connection represents a configured integration with credentials, health\nmonitoring, and usage tracking.\n\nLifecycle States:\n - ACTIVE: Connection is healthy and ready for sync operations\n - SUSPENDED: Temporarily disabled by user (credentials preserved)\n - FAILED: Health checks failing (may need credential refresh)\n - ARCHIVED: Permanently retired (cannot be reactivated)\n\nSecurity:\n - Sensitive credential fields are encrypted at rest using MongoDB\n client-side field level encryption (CSFLE)\n - Credentials never appear in API responses or logs\n - Failed authentication attempts are logged in last_error\n - Consecutive failures trigger automatic suspension\n\nUse Cases:\n - Connect to team Google Drive for document ingestion\n - Sync files from customer S3 buckets\n - Monitor and process uploaded media files\n - Schedule periodic sync operations\n\nHealth Monitoring:\n - Automatic health checks validate connectivity and credentials\n - consecutive_failures tracks authentication/network issues\n - Auto-disable after 5 consecutive failures to prevent lockout\n - last_error stores diagnostic information for debugging","examples":[{"connection_id":"conn_abc123def456ghi","created_by_user_id":"usr_admin123abc456","description":"Team drive for marketing assets","internal_id":"int_org123","is_active":true,"metadata":{"team":"marketing"},"name":"Marketing Google Drive","provider_config":{"credentials":{"client_email":"sync@project.iam.gserviceaccount.com","type":"service_account"},"provider_type":"google_drive","shared_drive_id":"0AH-Xabc123"},"provider_type":"google_drive","status":"active"},{"connection_id":"conn_xyz789uvw012qrs","created_by_user_id":"usr_admin123abc456","internal_id":"int_org123","is_active":true,"name":"Production S3 Bucket","provider_config":{"credentials":{"access_key_id":"AKIA..."},"provider_type":"s3","region":"us-east-1"},"provider_type":"s3","status":"active"}]},"StorageConnectionTestResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the connection test succeeded. True: Credentials are valid and connection is accessible. False: Authentication failed, network error, or permissions denied.","examples":[true,false]},"message":{"type":"string","title":"Message","description":"Human-readable message describing the test result. Success: 'Connection test succeeded' or similar. Failure: Error message explaining what went wrong.","examples":["Connection test succeeded","Authentication failed: Invalid credentials","Permission denied: Unable to access shared drive"]},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"OPTIONAL. Additional diagnostic information about the test result. May include error details, provider-specific information, or success metadata. Format varies by provider.","examples":[{"provider_response":"...","result":"success"},{"error":"Invalid credentials","error_code":"AUTH_FAILED"}]}},"type":"object","required":["success","message"],"title":"StorageConnectionTestResponse","description":"Response payload for connection test endpoint.\n\nReturns the result of testing connection credentials against the external\nprovider. Used to validate credentials before saving or to diagnose issues.","examples":[{"description":"Successful test","details":{"result":"success"},"message":"Connection test succeeded","success":true},{"description":"Failed test","details":{"error":"Invalid credentials","error_code":"AUTH_FAILED"},"message":"Authentication failed: Invalid credentials","success":false}]},"StorageConnectionUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Name","description":"OPTIONAL. New name for the connection. Must be unique within the organization if provided. Format: 1-100 characters.","examples":["Updated Drive Name","New S3 Connection"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"OPTIONAL. New description for the connection. Set to empty string to clear existing description. Format: Up to 500 characters."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"OPTIONAL. New metadata dictionary. Replaces existing metadata entirely (partial updates not supported). Set to empty dict {} to clear all metadata."},"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"OPTIONAL. New operational status. ACTIVE: Connection is healthy and ready for use. SUSPENDED: Temporarily disabled, credentials preserved. FAILED: Health checks failing. ARCHIVED: Permanently retired (cannot be reactivated)."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"OPTIONAL. Quick boolean flag for filtering. True when status is ACTIVE, False otherwise. Automatically maintained when status changes."},"provider_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Provider Config","description":"OPTIONAL. Updated provider configuration including credentials. Replaces entire provider_config (partial updates not supported). SECURITY: Sensitive fields are encrypted at rest."}},"type":"object","title":"StorageConnectionUpdateRequest","description":"Request payload for updating storage connection metadata.\n\nAllows partial updates to connection metadata without changing credentials.\nCredentials can be updated via provider_config.\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**Examples:**\n```python\n# Update name and description\n{\n \"name\": \"Updated Drive Name\",\n \"description\": \"New description\"\n}\n\n# Suspend connection\n{\n \"status\": \"suspended\",\n \"is_active\": False\n}\n\n# Refresh credentials\n{\n \"provider_config\": {\n \"credentials\": {...}\n }\n}\n```","examples":[{"description":"New description","name":"Updated Drive Name"},{"is_active":false,"status":"suspended"},{"provider_config":{"credentials":{"access_key_id":"AKIA..."}}}]},"StorageMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket","description":"Time bucket timestamp"},"total_size_bytes":{"type":"integer","title":"Total Size Bytes","description":"Total storage size in bytes"},"object_count":{"type":"integer","title":"Object Count","description":"Number of objects"},"avg_size_bytes":{"type":"integer","title":"Avg Size Bytes","description":"Average object size in bytes"},"growth_rate_percent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Rate Percent","description":"Growth rate vs previous period"}},"type":"object","required":["time_bucket","total_size_bytes","object_count","avg_size_bytes"],"title":"StorageMetric","description":"Single time bucket storage metric."},"StorageProvider":{"type":"string","enum":["google_drive","s3","snowflake","sharepoint","tigris","postgresql","instagram","tiktok","rss","http_api","box"],"title":"StorageProvider","description":"Supported external storage providers for ingestion and sync.\n\nMixpeek can connect to external storage providers to automatically\ningest objects and keep them synchronized with your namespaces.\n\nProviders:\n GOOGLE_DRIVE: Google Drive and Google Workspace shared drives.\n - Authentication: Service account or OAuth2\n - Features: Shared drive support, real-time sync, metadata preservation\n - Use cases: Marketing assets, team documents, knowledge bases\n - Limitations: Rate limits apply (10,000 requests/100 seconds per user)\n\n S3: Amazon S3 and S3-compatible storage (MinIO, DigitalOcean Spaces, etc).\n - Authentication: Access keys or IAM role assumption\n - Features: Bucket notifications, prefix filtering, versioning support\n - Use cases: Data lakes, video archives, ML datasets, backups\n - Limitations: IAM role assumption preferred over access keys\n\n SNOWFLAKE: Snowflake data warehouse tables.\n - Authentication: Key pair or username/password\n - Features: Incremental sync via watermarks, row-level mapping, schema introspection\n - Use cases: Customer data tables, product catalogs, transaction logs, metadata tables\n - Limitations: Each row becomes one object; large tables require incremental column\n\n SHAREPOINT: Microsoft SharePoint and OneDrive for Business.\n - Authentication: Azure AD OAuth2 (client credentials or delegated)\n - Features: Site/drive selection, folder sync, delta queries for incremental sync\n - Use cases: Enterprise documents, team collaboration files, compliance archives\n - Limitations: Requires Azure AD app registration; throttling limits apply\n\nConnection Requirements:\n - Valid credentials with read access to target files/buckets\n - Network connectivity from Mixpeek infrastructure\n - Appropriate IAM policies or share permissions configured\n\nExamples:\n - Use GOOGLE_DRIVE for syncing team marketing materials\n - Use S3 for ingesting video archives from data lakes\n - Use S3 with IAM role for secure production deployments\n - Use SHAREPOINT for syncing enterprise SharePoint document libraries\n\n TIGRIS: Tigris Data globally distributed object storage (S3-compatible).\n - Authentication: Access keys (same format as S3)\n - Features: S3-compatible API, global distribution, zero egress fees\n - Use cases: Globally distributed media, low-latency content delivery\n - Endpoint: https://fly.storage.tigris.dev\n\n POSTGRESQL: PostgreSQL relational database.\n - Authentication: Username/password\n - Features: SQL queries, incremental sync via watermarks, row-level mapping\n - Use cases: Customer data tables, product catalogs, transaction logs\n - Limitations: Each row becomes one object; large tables require incremental column\n\n INSTAGRAM: Instagram Business/Creator accounts via Meta Graph API.\n - Authentication: OAuth 2.0 via Meta Developer Console\n - Features: Media sync (posts, reels, carousels), engagement metrics, captions\n - Use cases: Social media content analysis, talent scouting, competitor monitoring\n - Limitations: Requires Instagram Business/Creator account; long-lived tokens (60 days) need refresh\n\n TIKTOK: TikTok accounts via TikTok Content API.\n - Authentication: OAuth 2.0 via TikTok Login Kit\n - Features: Video sync, engagement metrics (likes, views, shares), descriptions\n - Use cases: Social media content analysis, creator discovery, trend monitoring\n - Limitations: Access tokens expire in 24h (refresh_token flow); rate limits apply\n\n RSS: RSS/Atom feed entries.\n - Authentication: Optional HTTP headers (most feeds are public)\n - Features: Entry-level sync with title, author, categories, content\n - Use cases: News monitoring, blog ingestion, content aggregation\n - Limitations: No pagination; feeds are fetched in full each poll\n\n HTTP_API: Arbitrary REST/HTTP JSON APIs.\n - Authentication: Optional HTTP headers (API keys, Bearer tokens, etc.)\n - Features: Configurable JSONPath to items array, dedup via item ID field,\n incremental sync via timestamp field, GET or POST methods, JSON or JSONL responses\n - Use cases: Public APIs (Hacker News, GitHub), private APIs (Stripe, internal services),\n any JSON endpoint that returns a list of items\n - Limitations: No built-in pagination; API is fetched in full each poll\n\n BOX: Box cloud content management and file sharing.\n - Authentication: OAuth 2.0 (JWT or Client Credentials Grant with CCG)\n - Features: Folder sync, enterprise content management, metadata, versioning\n - Use cases: Enterprise document management, compliance archives, collaboration files\n - Limitations: Rate limits apply (10 API calls per second per user)"},"StorageStatistics":{"properties":{"total_size_bytes":{"type":"integer","title":"Total Size Bytes","description":"Total size of all objects/blobs in the bucket in bytes","default":0},"avg_size_bytes":{"type":"integer","title":"Avg Size Bytes","description":"Average object size in bytes","default":0},"max_size_bytes":{"type":"integer","title":"Max Size Bytes","description":"Size of the largest object in bytes","default":0},"min_size_bytes":{"type":"integer","title":"Min Size Bytes","description":"Size of the smallest object in bytes","default":0}},"type":"object","title":"StorageStatistics","description":"Statistics about object storage in a bucket."},"StructuredDataConfig":{"properties":{"type":{"type":"string","title":"Type","description":"Schema.org type for structured data","default":"WebApplication","examples":["WebApplication","SearchAction","WebPage","SoftwareApplication"]},"additional_properties":{"additionalProperties":true,"type":"object","title":"Additional Properties","description":"Additional Schema.org properties","examples":[{"applicationCategory":"Search","operatingSystem":"Web"},{"potentialAction":{"@type":"SearchAction","target":"{search_term}"}}]}},"type":"object","title":"StructuredDataConfig","description":"Schema.org structured data configuration for search engines.\n\nEnables rich search results and better understanding of the page content."},"SubmitBatchRequest":{"properties":{"include_processing_history":{"type":"boolean","title":"Include Processing History","description":"OPTIONAL (defaults to True). Controls whether processing operations are tracked in document internal_metadata.processing_history. When True: Each enrichment operation (taxonomy application, clustering, etc.) adds an audit trail entry. When False: Documents are enriched without processing history tracking, resulting in cleaner metadata. Use True for: Debugging, audit requirements, lineage tracking, understanding document transformations. Use False for: Production workloads where metadata size matters, simplified document structure. Processing history entries include: operation type, timestamp, and IDs of applied resources (taxonomies, clusters, etc.).","default":true,"examples":[true,false]}},"type":"object","title":"SubmitBatchRequest","description":"Request model for submitting a batch for processing.\n\nThis model allows configuration of processing behavior for the batch,\nsuch as whether to track processing history in document metadata.\n\nUse Cases:\n - Submit batch with full audit trail (include_processing_history=True)\n - Submit batch without processing history for cleaner metadata (include_processing_history=False)\n - Default behavior includes processing history for debugging and lineage tracking\n\nRequirements:\n - include_processing_history: OPTIONAL, defaults to True","examples":[{"description":"Submit batch with processing history (default)","include_processing_history":true},{"description":"Submit batch without processing history","include_processing_history":false},{"description":"Submit batch with default settings (includes processing history)"}]},"SubmitFeedbackRequest":{"properties":{"message_id":{"type":"string","title":"Message Id","description":"Assistant message ID (REQUIRED)"},"rating":{"type":"string","pattern":"^(positive|negative)$","title":"Rating","description":"Feedback rating: 'positive' or 'negative' (REQUIRED)"},"feedback_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback Text","description":"Additional feedback text (OPTIONAL)"}},"type":"object","required":["message_id","rating"],"title":"SubmitFeedbackRequest","description":"Request payload for submitting feedback on a message.\n\nAttributes:\n message_id: The assistant message ID to provide feedback for\n rating: Feedback rating (positive or negative)\n feedback_text: Optional additional feedback text\n\nExample:\n ```python\n request = SubmitFeedbackRequest(\n message_id=\"msg_abc123\",\n rating=\"positive\",\n feedback_text=\"This was very helpful!\"\n )\n ```","examples":[{"feedback_text":"Great response!","message_id":"msg_abc123","rating":"positive"}]},"SubmitFeedbackResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session identifier"},"message_id":{"type":"string","title":"Message Id","description":"Message identifier"},"rating":{"type":"string","title":"Rating","description":"Feedback rating submitted"},"stored":{"type":"boolean","title":"Stored","description":"Whether exchange was stored to memory"},"recorded_at":{"type":"string","format":"date-time","title":"Recorded At","description":"Feedback timestamp"}},"type":"object","required":["session_id","message_id","rating","stored","recorded_at"],"title":"SubmitFeedbackResponse","description":"Response for feedback submission.\n\nAttributes:\n session_id: Session identifier\n message_id: Message that received feedback\n rating: The feedback rating submitted\n stored: Whether the exchange was stored to memory\n recorded_at: Timestamp when feedback was recorded\n\nExample:\n ```python\n response = SubmitFeedbackResponse(\n session_id=\"ses_abc123\",\n message_id=\"msg_xyz789\",\n rating=\"positive\",\n stored=True,\n recorded_at=datetime.utcnow()\n )\n ```"},"SubscriptionStatus":{"type":"string","enum":["active","cancelled","expired","suspended","pending"],"title":"SubscriptionStatus","description":"Status of a marketplace subscription."},"SubscriptionTier":{"type":"string","enum":["free","basic","pro","enterprise"],"title":"SubscriptionTier","description":"Subscription tier levels for marketplace offerings."},"SubscriptionTierConfig":{"properties":{"tier":{"$ref":"#/components/schemas/SubscriptionTier","description":"Tier level"},"price_per_month":{"type":"number","minimum":0.0,"title":"Price Per Month","description":"Monthly price in USD (0.0 for free tier)","default":0.0},"limits":{"$ref":"#/components/schemas/TierLimits","description":"Rate limits and quotas for this tier"},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"List of features included in this tier"},"stripe_price_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Price Id","description":"Stripe price ID for paid tiers"}},"type":"object","required":["tier"],"title":"SubscriptionTierConfig","description":"Configuration for a subscription tier."},"SuitableCollection":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"Collection ID"},"collection_name":{"type":"string","title":"Collection Name","description":"Collection name"},"feature_extractor":{"type":"string","title":"Feature Extractor","description":"Feature extractor name"},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","description":"Collection capabilities"},"match_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Match Score","description":"Match confidence"}},"type":"object","required":["collection_id","collection_name","feature_extractor","match_score"],"title":"SuitableCollection","description":"Information about a collection that might fulfill the user's request.\n\nAttributes:\n collection_id: Collection identifier\n collection_name: Human-readable collection name\n feature_extractor: Extractor used in this collection\n capabilities: What this collection can do (e.g., \"video search\", \"face detection\")\n match_score: How well this collection matches the request (0.0-1.0)"},"SyncComparisonResponse":{"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"},"configs":{"items":{"$ref":"#/components/schemas/SyncConfigMetric"},"type":"array","title":"Configs","description":"Metrics per sync config"}},"type":"object","required":["bucket_id","time_range","configs"],"title":"SyncComparisonResponse","description":"Sync configuration comparison response."},"SyncConfigMetric":{"properties":{"sync_config_id":{"type":"string","title":"Sync Config Id","description":"Sync config identifier"},"provider_type":{"type":"string","title":"Provider Type","description":"Provider type"},"avg_duration_seconds":{"type":"number","title":"Avg Duration Seconds","description":"Average sync duration"},"avg_throughput_mbps":{"type":"number","title":"Avg Throughput Mbps","description":"Average throughput"},"success_rate":{"type":"number","title":"Success Rate","description":"Success rate (0-1)"},"total_files_synced":{"type":"integer","title":"Total Files Synced","description":"Total files synced"},"total_bytes_synced":{"type":"integer","title":"Total Bytes Synced","description":"Total bytes synced"}},"type":"object","required":["sync_config_id","provider_type","avg_duration_seconds","avg_throughput_mbps","success_rate","total_files_synced","total_bytes_synced"],"title":"SyncConfigMetric","description":"Sync configuration comparison metrics."},"SyncConfigurationModel":{"properties":{"sync_config_id":{"type":"string","title":"Sync Config Id","description":"Unique identifier for the sync configuration."},"bucket_id":{"type":"string","title":"Bucket Id","description":"Target bucket identifier (e.g. 'bkt_marketing_assets')."},"connection_id":{"type":"string","title":"Connection Id","description":"Storage connection identifier (e.g. 'conn_abc123')."},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal identifier (multi-tenancy scope)."},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace identifier owning the bucket."},"source_path":{"type":"string","title":"Source Path","description":"Source path in the external storage provider. Format varies by provider: s3/tigris='bucket/prefix', google_drive='folder_id', sharepoint='/sites/Name/Documents', snowflake='DB.SCHEMA.TABLE'."},"file_filters":{"anyOf":[{"$ref":"#/components/schemas/FileFilters"},{"type":"null"}],"description":"Optional filter rules limiting which files are synced."},"schema_mapping":{"anyOf":[{"$ref":"#/components/schemas/SchemaMapping-Output"},{"type":"null"}],"description":"Schema mapping defining how source data maps to bucket schema fields. Maps external storage attributes (tags, metadata, columns, filenames) to bucket schema fields and blob properties. When provided, enables structured extraction of metadata from the sync source. See SchemaMapping for detailed configuration options."},"sync_mode":{"$ref":"#/components/schemas/SyncMode","description":"Sync mode controlling lifecycle (initial_only or continuous).","default":"continuous"},"polling_interval_seconds":{"type":"integer","maximum":900.0,"minimum":30.0,"title":"Polling Interval Seconds","description":"Polling interval in seconds (continuous mode).","default":300},"batch_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Batch Size","description":"Number of files processed per sync batch.","default":50},"create_object_on_confirm":{"type":"boolean","title":"Create Object On Confirm","description":"Whether objects should be created immediately after confirmation.","default":true},"skip_duplicates":{"type":"boolean","title":"Skip Duplicates","description":"Skip files whose hashes already exist in the bucket.","default":true},"skip_batch_submission":{"type":"boolean","title":"Skip Batch Submission","description":"If True, sync objects to the bucket without creating/submitting batches for processing.","default":false},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"Current lifecycle status for the sync configuration. PENDING: Not yet started. ACTIVE: Currently running/polling. SUSPENDED: Temporarily paused. COMPLETED: Initial sync completed (for initial_only mode). FAILED: Sync encountered errors.","default":"PENDING"},"is_active":{"type":"boolean","title":"Is Active","description":"Convenience flag used for filtering active syncs.","default":true},"total_files_discovered":{"type":"integer","minimum":0.0,"title":"Total Files Discovered","description":"Cumulative count of files found in source across all runs.","default":0},"total_files_synced":{"type":"integer","minimum":0.0,"title":"Total Files Synced","description":"Cumulative count of successfully synced files.","default":0},"total_files_failed":{"type":"integer","minimum":0.0,"title":"Total Files Failed","description":"Cumulative count of failed files (sent to DLQ after 3 retries).","default":0},"total_bytes_synced":{"type":"integer","minimum":0.0,"title":"Total Bytes Synced","description":"Cumulative bytes transferred across all runs.","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When sync configuration was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last modification timestamp."},"last_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sync At","description":"When last successful sync completed. Used for incremental syncs."},"next_sync_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Sync At","description":"Scheduled time for next sync (continuous/scheduled modes)."},"created_by_user_id":{"type":"string","title":"Created By User Id","description":"User identifier that created the sync configuration."},"last_error":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Last Error","description":"Most recent error message if sync attempts failed."},"consecutive_failures":{"type":"integer","minimum":0.0,"title":"Consecutive Failures","default":0},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary metadata supplied by the user."},"locked_by_worker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locked By Worker Id","description":"Worker ID that currently holds the lock for this sync"},"locked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Locked At","description":"Timestamp when lock was acquired"},"lock_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Lock Expires At","description":"Timestamp when lock expires (for stale lock recovery)"},"paused":{"type":"boolean","title":"Paused","description":"Whether sync is currently paused (user-controlled)","default":false},"pause_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pause Reason","description":"Reason for pause"},"paused_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paused At","description":"Timestamp when paused"},"paused_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused By User Id","description":"User who paused the sync"},"max_objects_per_run":{"type":"integer","minimum":1.0,"title":"Max Objects Per Run","description":"Hard cap on objects per sync run (prevents runaway syncs)","default":100000},"max_batch_chunk_size":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Max Batch Chunk Size","description":"Maximum objects per batch chunk","default":1000},"batch_chunk_size":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Batch Chunk Size","description":"Number of objects per batch chunk (for concurrent processing)","default":100},"current_sync_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Sync Run Id","description":"UUID for current/last sync run"},"sync_run_counter":{"type":"integer","minimum":0.0,"title":"Sync Run Counter","description":"Increments on each sync execution","default":0},"batch_ids":{"items":{"type":"string"},"type":"array","title":"Batch Ids","description":"List of batch IDs created by this sync"},"task_ids":{"items":{"type":"string"},"type":"array","title":"Task Ids","description":"List of task IDs for batches"},"batches_created":{"type":"integer","minimum":0.0,"title":"Batches Created","description":"Total number of batches created","default":0},"resume_enabled":{"type":"boolean","title":"Resume Enabled","description":"Whether resuming partial runs is enabled","default":true},"resume_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resume Cursor","description":"Last page/cursor processed (for paginated APIs like Google Drive)"},"resume_last_primary_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resume Last Primary Key","description":"Last primary key processed (for database syncs with stable ordering)"},"resume_objects_processed":{"type":"integer","minimum":0.0,"title":"Resume Objects Processed","description":"Count of objects processed in current/last run","default":0},"resume_checkpoint_frequency":{"type":"integer","maximum":10000.0,"minimum":100.0,"title":"Resume Checkpoint Frequency","description":"How often to checkpoint (in objects). Default: every 1000 objects","default":1000}},"type":"object","required":["bucket_id","connection_id","internal_id","namespace_id","source_path","created_by_user_id"],"title":"SyncConfigurationModel","description":"Bucket-scoped configuration for automated storage synchronization.\n\nDefines how files are synced from external storage providers to a Mixpeek bucket.\nIncludes configuration, status, metrics, and robustness control fields.\n\n**Supported Providers:** google_drive, s3, snowflake, sharepoint, tigris\n\n**Built-in Robustness:**\n- Distributed locking (locked_by_worker_id, lock_expires_at)\n- Pause/resume control (paused, pause_reason, paused_at)\n- Safety limits (max_objects_per_run, batch_chunk_size)\n- Resume checkpointing (resume_cursor, resume_objects_processed)\n- Batch tracking (batch_ids, task_ids, batches_created)\n\n**Metrics Fields:**\n- total_files_discovered: Files found in source\n- total_files_synced: Successfully synced files\n- total_files_failed: Files that failed (check DLQ)\n- total_bytes_synced: Total data transferred\n- consecutive_failures: Failure count for auto-suspend"},"SyncCreateRequest":{"properties":{"connection_id":{"type":"string","title":"Connection Id","description":"REQUIRED. Storage connection identifier to sync from. Must reference an existing connection created via POST /organizations/connections. The connection defines the storage provider and credentials. Supported providers: google_drive, s3, snowflake, sharepoint, tigris.","examples":["conn_abc123","conn_s3_prod"]},"source_path":{"type":"string","title":"Source Path","description":"REQUIRED. Source path within the storage provider to monitor and sync. Path format varies by provider: - s3/tigris: 'bucket-name/prefix' or 'bucket-name'. - google_drive: folder ID or path like '/Marketing/Assets'. - sharepoint: '/sites/SiteName/Shared Documents/folder'. - snowflake: 'DATABASE.SCHEMA.TABLE' or just 'TABLE' if defaults set.","examples":["my-bucket/videos","0AH-Xabc123","PROD.PUBLIC.CUSTOMERS"]},"sync_mode":{"$ref":"#/components/schemas/SyncMode","description":"Synchronization mode determining how files are monitored and ingested. OPTIONAL. Defaults to 'continuous'. 'continuous': Actively monitors for new files and syncs immediately. 'one_time': Performs a single sync of existing files then stops. 'scheduled': Syncs on polling intervals only.","default":"continuous","examples":["continuous","one_time","scheduled"]},"file_filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"File Filters","description":"OPTIONAL. Filters to control which files are synced. When omitted, all files in source_path are synced. Supported filters: - include_patterns: Glob patterns to include (e.g., ['*.mp4', '*.mov']). - exclude_patterns: Glob patterns to exclude (e.g., ['*.tmp', '.DS_Store']). - extensions: File extensions to include (e.g., ['.mp4', '.jpg']). - min_size_bytes: Minimum file size in bytes. - max_size_bytes: Maximum file size in bytes. - modified_after: ISO datetime, only sync files modified after this time. - mime_types: List of MIME types to include (e.g., ['video/*', 'image/jpeg']).","examples":[{"extensions":[".mp4",".mov"]},{"include_patterns":["*.jpg","*.png"],"min_size_bytes":1024},{"exclude_patterns":["*.tmp","thumbs/*"],"max_size_bytes":52428800},{"mime_types":["video/*"],"modified_after":"2024-01-01T00:00:00Z"}]},"schema_mapping":{"anyOf":[{"$ref":"#/components/schemas/SchemaMapping-Input"},{"type":"null"}],"description":"OPTIONAL. Defines how source data maps to bucket schema fields and blobs. When provided, enables structured extraction of metadata from the sync source. Keys are target bucket schema field names, values define the source extraction method. \n\n**Blob Mappings** (target_type='blob'): Map files or URLs to blob fields. Use source.type='file' for the synced file itself, or source.type='column'/'metadata' for URLs. \n\n**Field Mappings** (target_type='field'): Map metadata to schema fields. Source options by provider: - S3/Tigris: 'tag' (object tags), 'metadata' (x-amz-meta-*) - Snowflake: 'column' (table columns) - Google Drive: 'drive_property' (file properties) - All: 'filename_regex', 'folder_path', 'constant' \n\nIf omitted, default behavior depends on provider - typically maps file to 'content' blob.","examples":[{"mappings":{"category":{"source":{"key":"category","type":"tag"},"target_type":"field"},"content":{"blob_type":"auto","source":{"type":"file"},"target_type":"blob"}}},{"mappings":{"content":{"blob_type":"video","source":{"type":"file"},"target_type":"blob"},"project":{"source":{"segment":0,"type":"folder_path"},"target_type":"field","transform":"lowercase"}}}]},"polling_interval_seconds":{"type":"integer","maximum":900.0,"minimum":30.0,"title":"Polling Interval Seconds","description":"Interval in seconds between polling checks for new files. OPTIONAL. Defaults to 300 seconds (5 minutes). Must be between 30 and 900 seconds (0.5 to 15 minutes). Only applies to 'continuous' and 'scheduled' sync modes. Lower values mean faster detection but higher API usage.","default":300,"examples":[60,300,600]},"batch_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Batch Size","description":"Number of files to process in each batch during sync. OPTIONAL. Defaults to 50 files per batch. Must be between 1 and 100. Larger batches improve throughput but require more memory. Smaller batches provide more granular progress tracking.","default":50,"examples":[10,50,100]},"skip_batch_submission":{"type":"boolean","title":"Skip Batch Submission","description":"If True, sync objects to the bucket without creating or submitting batches for collection processing. Objects are created in the bucket but no tier processing is triggered. Useful for bulk data migration or when you want to manually control when processing occurs. OPTIONAL. Defaults to False (batches are created and submitted).","default":false,"examples":[false,true]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional custom metadata to attach to the sync configuration. NOT REQUIRED. Arbitrary key-value pairs for tagging and organization. Common uses: project tags, environment labels, cost centers. Maximum 50 keys, values must be JSON-serializable.","examples":[{"environment":"production","project":"video-pipeline"},{"cost_center":"marketing","owner":"data-team"}]}},"type":"object","required":["connection_id","source_path"],"title":"SyncCreateRequest","description":"Request to create a bucket sync configuration.\n\nEstablishes automated synchronization between a storage connection and a bucket.\nThe sync monitors the source path for changes and ingests files according to\nthe specified mode and filters.\n\nSupported Storage Providers:\n - google_drive: Google Drive and Workspace shared drives\n - s3: Amazon S3 and S3-compatible (MinIO, DigitalOcean Spaces, Wasabi)\n - snowflake: Snowflake data warehouse tables (rows become objects)\n - sharepoint: Microsoft SharePoint and OneDrive for Business\n - tigris: Tigris globally distributed object storage\n\nRobustness Features (built-in):\n - Dead Letter Queue (DLQ): Failed objects tracked with 3 retries before quarantine\n - Idempotent ingestion: Deduplication via (bucket_id, source_provider, source_object_id)\n - Distributed locking: Prevents concurrent execution of same sync config\n - Rate limit handling: Automatic backoff on provider 429 responses\n - Metrics: Duration, files synced/failed, batches created, rate limit hits\n\nSync Modes:\n - continuous: Real-time monitoring with polling interval\n - one_time: Single bulk import then stops\n - scheduled: Polling-based batch imports\n\nRequirements:\n - connection_id: REQUIRED, must be an existing connection\n - source_path: REQUIRED, path must exist in the storage provider\n - sync_mode: OPTIONAL, defaults to 'continuous'\n - All other fields are OPTIONAL with sensible defaults","examples":[{"batch_size":50,"connection_id":"conn_s3_prod","description":"S3: Continuous video sync with filters","file_filters":{"extensions":[".mp4",".mov"],"min_size_bytes":1024},"metadata":{"project":"video-analysis"},"polling_interval_seconds":300,"source_path":"media-bucket/videos/raw","sync_mode":"continuous"},{"batch_size":100,"connection_id":"conn_gdrive_marketing","description":"Google Drive: One-time folder import","file_filters":{"mime_types":["image/*","video/*"]},"source_path":"0AH-Xabc123def456","sync_mode":"one_time"},{"batch_size":100,"connection_id":"conn_snowflake_prod","description":"Snowflake: Scheduled table sync","metadata":{"incremental":true},"polling_interval_seconds":900,"source_path":"ANALYTICS.PUBLIC.CUSTOMERS","sync_mode":"scheduled"},{"connection_id":"conn_sharepoint_legal","description":"SharePoint: Document library sync","file_filters":{"extensions":[".pdf",".docx"]},"polling_interval_seconds":600,"source_path":"/sites/Legal/Shared Documents/Contracts","sync_mode":"continuous"},{"batch_size":100,"connection_id":"conn_tigris_cdn","description":"Tigris: Global media sync","file_filters":{"include_patterns":["*.jpg","*.webp"]},"source_path":"cdn-assets/media","sync_mode":"continuous"}]},"SyncHealthMetric":{"properties":{"sync_config_id":{"type":"string","title":"Sync Config Id","description":"Sync config identifier"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Consecutive failure count"},"last_success_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Success At","description":"Last successful sync"},"last_failure_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Failure At","description":"Last failed sync"},"failure_rate":{"type":"number","title":"Failure Rate","description":"Failure rate (0-1)"}},"type":"object","required":["sync_config_id","consecutive_failures","failure_rate"],"title":"SyncHealthMetric","description":"Sync health metrics per config."},"SyncListResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SyncConfigurationModel"},"type":"array","title":"Results","description":"List of sync configurations matching the query filters. ALWAYS PRESENT. May be empty if no configurations match. Each item is a complete SyncConfigurationModel. Ordered by creation date (newest first)."},"pagination":{"$ref":"#/components/schemas/PaginationResponse","description":"Pagination metadata for navigating result sets. ALWAYS PRESENT. Contains next/previous links, current page info. Use the provided links for cursor-based pagination."},"total":{"type":"integer","title":"Total","description":"Total number of sync configurations matching the filters. ALWAYS PRESENT. Useful for progress indicators and UI display. Note: This is the total across all pages, not just current page.","examples":[0,5,42]}},"type":"object","required":["results","pagination","total"],"title":"SyncListResponse","description":"Response containing a list of sync configurations with pagination.\n\nWraps the list of sync configurations with pagination metadata\nto support efficient browsing of large result sets.\n\nResponse Structure:\n - results: The actual sync configuration objects\n - pagination: Links and metadata for navigation\n - total: Total count for client-side progress indicators","examples":[{"description":"Empty result set","pagination":{"limit":10,"offset":0},"results":[],"total":0},{"description":"Single page with results","pagination":{"limit":10,"offset":0},"results":[{"bucket_id":"bucket_xyz","connection_id":"conn_s3_prod","is_active":true,"source_path":"videos/raw","status":"processing","sync_config_id":"sync_abc123","sync_mode":"continuous"}],"total":1}]},"SyncMode":{"type":"string","enum":["initial_only","continuous"],"title":"SyncMode","description":"Supported sync modes for external storage ingestion."},"SyncPerformanceResponse":{"properties":{"bucket_id":{"type":"string","title":"Bucket Id","description":"Bucket identifier"},"sync_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Config Id","description":"Optional sync config filter"},"time_range":{"$ref":"#/components/schemas/api__analytics__buckets__models__TimeRange","description":"Query time range"},"runs":{"items":{"$ref":"#/components/schemas/SyncRunMetric"},"type":"array","title":"Runs","description":"Sync run metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Summary statistics"}},"type":"object","required":["bucket_id","time_range","runs"],"title":"SyncPerformanceResponse","description":"Sync performance analytics response."},"SyncRunMetric":{"properties":{"sync_run_id":{"type":"string","title":"Sync Run Id","description":"Sync run identifier"},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"Sync start time"},"duration_seconds":{"type":"number","title":"Duration Seconds","description":"Sync duration in seconds"},"files_discovered":{"type":"integer","title":"Files Discovered","description":"Files discovered"},"files_synced":{"type":"integer","title":"Files Synced","description":"Files successfully synced"},"files_failed":{"type":"integer","title":"Files Failed","description":"Files that failed"},"bytes_synced":{"type":"integer","title":"Bytes Synced","description":"Bytes synced"},"throughput_mbps":{"type":"number","title":"Throughput Mbps","description":"Throughput in MB/s"},"status":{"type":"string","title":"Status","description":"Sync status"},"provider_type":{"type":"string","title":"Provider Type","description":"Provider type (s3, gcs, etc)"}},"type":"object","required":["sync_run_id","started_at","duration_seconds","files_discovered","files_synced","files_failed","bytes_synced","throughput_mbps","status","provider_type"],"title":"SyncRunMetric","description":"Single sync run metrics."},"SyncUpdateRequest":{"properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional human-readable description of the sync configuration. NOT REQUIRED. Used for documentation and UI display. Maximum 500 characters.","examples":["Daily video ingestion from production bucket"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional custom metadata to replace existing metadata. NOT REQUIRED. Completely replaces existing metadata (not merged). Use for tagging, categorization, or custom attributes. Maximum 50 keys, values must be JSON-serializable.","examples":[{"environment":"production","project":"video-pipeline"},{"last_updated":"2025-11-01","owner":"data-team"}]},"status":{"anyOf":[{"$ref":"#/components/schemas/TaskStatusEnum"},{"type":"null"}],"description":"Optional status to set for the sync configuration. NOT REQUIRED. Valid values: 'pending', 'processing', 'completed', 'failed', 'paused'. Typically managed automatically but can be manually overridden. Use pause/resume endpoints instead for active control.","examples":["pending","processing","completed"]},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Optional flag to enable or disable the sync configuration. NOT REQUIRED. When False, sync will not process new files. Prefer using the /pause and /resume endpoints for clarity. Changes take effect immediately.","examples":[true,false]},"polling_interval_seconds":{"anyOf":[{"type":"integer","maximum":900.0,"minimum":30.0},{"type":"null"}],"title":"Polling Interval Seconds","description":"Optional new polling interval in seconds. NOT REQUIRED. Must be between 30 and 900 seconds if provided. Only applies to 'continuous' and 'scheduled' sync modes. Lower values increase responsiveness but API usage.","examples":[60,300,600]},"batch_size":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Batch Size","description":"Optional new batch size for file processing. NOT REQUIRED. Must be between 1 and 100 if provided. Larger batches improve throughput but use more memory. Changes apply to subsequent batches only.","examples":[10,50,100]},"schema_mapping":{"anyOf":[{"$ref":"#/components/schemas/SchemaMapping-Input"},{"type":"null"}],"description":"Optional schema mapping to replace existing mapping. NOT REQUIRED. Completely replaces existing schema_mapping (not merged). Defines how source data maps to bucket schema fields and blobs. See SyncCreateRequest.schema_mapping for detailed documentation."},"skip_batch_submission":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Batch Submission","description":"If True, sync objects to the bucket without creating or submitting batches for collection processing. Objects are created in the bucket but no tier processing is triggered. NOT REQUIRED. When omitted, existing value is preserved.","examples":[false,true]}},"type":"object","title":"SyncUpdateRequest","description":"Request to update an existing sync configuration.\n\nAllows partial updates to sync settings without recreating the configuration.\nAll fields are optional - only provided fields will be updated.\n\nUse Cases:\n - Pause/resume syncs by toggling is_active\n - Adjust polling intervals based on activity patterns\n - Update batch sizes for performance tuning\n - Add metadata tags for organization\n\nRequirements:\n - All fields are OPTIONAL\n - At least one field should be provided for the update\n - Changes take effect on the next sync cycle","examples":[{"description":"Pause sync temporarily","is_active":false},{"description":"Adjust polling frequency","polling_interval_seconds":600},{"batch_size":75,"description":"Update batch size and metadata","metadata":{"last_tuned":"2025-11-01","optimized":true}},{"batch_size":100,"description":"Production video sync - optimized settings","is_active":true,"metadata":{"priority":"high","project":"video-ai"},"polling_interval_seconds":120},{"description":"Enable sync-only mode (no batch processing)","skip_batch_submission":true}]},"TaskProgress":{"properties":{"processed_documents":{"type":"integer","title":"Processed Documents","description":"Number of documents processed","default":0},"total_documents":{"type":"integer","title":"Total Documents","description":"Total documents to process","default":0},"percentage":{"type":"number","title":"Percentage","description":"Progress percentage (0-100)","default":0.0}},"type":"object","title":"TaskProgress","description":"Progress information for a task."},"TaskResponse":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Unique identifier for the task. REQUIRED. Used to poll task status via GET /v1/tasks/{task_id}. This ID is also stored on parent resources (batches, clusters, etc.) for cross-referencing. Format: UUID v4 or custom string identifier.","examples":["task_abc123def456","550e8400-e29b-41d4-a716-446655440000"]},"task_type":{"$ref":"#/components/schemas/TaskType","description":"Type of operation this task represents. REQUIRED. Identifies the specific async operation being performed. Used for filtering and categorizing tasks. Common types: api_buckets_batches_process, engine_cluster_build, api_taxonomies_execute. See TaskType enum for complete list of supported operations.","examples":["api_buckets_batches_process","engine_cluster_build","api_taxonomies_execute"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"Current status of the task. REQUIRED. Indicates the current state of the async operation. Terminal statuses (COMPLETED, FAILED, CANCELED) indicate the task has finished and will not change. Active statuses (PENDING, IN_PROGRESS, PROCESSING) indicate the task is still running and should be polled. Use this field to determine when to stop polling.","examples":["PENDING","PROCESSING","COMPLETED","FAILED"]},"inputs":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]},"type":"array"},{"type":"null"}],"title":"Inputs","description":"Input parameters or data used to start the task. OPTIONAL. May include IDs, configuration objects, or file references. Useful for debugging and understanding what data the task processed. Format: List of strings (IDs) or objects (configuration). Example: ['batch_id_123'] or [{'bucket_id': 'bkt_abc', 'config': {...}}]","examples":[["batch_xyz789"],["obj_123","obj_456","obj_789"],[{"bucket_id":"bkt_abc","collection_ids":["col_1","col_2"]}]]},"outputs":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]},"type":"array"},{"type":"null"}],"title":"Outputs","description":"Output results produced by the task. OPTIONAL. Populated when task completes successfully. May include processed file IDs, result metrics, or status summaries. Check this field after task reaches COMPLETED status to get results. Format: List of strings (output IDs) or objects (result data).","examples":[["document_123","document_456"],[{"failed_count":2,"processed_count":100,"success_rate":0.98}],[{"cluster_id":"cl_abc123","num_clusters":5}]]},"additional_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Additional Data","description":"Additional metadata and context for the task. OPTIONAL. Contains job IDs, error details, progress info, and other task-specific metadata. \n\nCommon fields (all task types): - 'error': Error message if task failed - 'job_id': Ray job ID for engine tasks - 'from_mongodb': True if retrieved from MongoDB fallback (not Redis) \n\nBatch-specific fields (task_type=api_buckets_batches_process): - 'batch_id': Batch identifier (REQUIRED) - 'bucket_id': Source bucket identifier (REQUIRED) - 'namespace_id': Namespace identifier (REQUIRED) - 'current_tier': Currently processing tier number, 0-indexed (OPTIONAL, None if not started) - 'total_tiers': Total number of tiers in the batch pipeline (REQUIRED) - 'collection_ids': Array of ALL collection IDs across all tiers (REQUIRED) - 'object_count': Number of objects being processed (REQUIRED) - 'sample_object_ids': First 5 object IDs for debugging/display (OPTIONAL) \n\nPerformance Note: Full object_ids array is NOT stored in task metadata to avoid bloating task documents (batches with 10k+ objects would add 200KB+ per task). For full object list, query the batch directly via GET /v1/buckets/{bucket_id}/batches/{batch_id}. \n\nNote: For detailed per-tier status, use GET /v1/buckets/{bucket_id}/batches/{batch_id} to access the tier_tasks[] array which contains individual tier statuses, collection_ids, and timestamps for each tier.","examples":[{"batch_id":"btch_xyz789","bucket_id":"bkt_products","collection_ids":["col_tier0","col_tier1","col_tier2"],"current_tier":1,"job_id":"ray_job_123","namespace_id":"ns_abc123","object_count":10000,"sample_object_ids":["obj_001","obj_002","obj_003","obj_004","obj_005"],"total_tiers":3},{"error":"Failed to process object: Invalid file format","job_id":"123"},{"cluster_id":"cl_abc","collection_ids":["col_1"],"from_mongodb":true}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Flattened error message for convenient error handling. OPTIONAL. Automatically populated from additional_data['error'] when the task has FAILED status. This is a convenience field - the full error details are always available in additional_data['error']. Use this field for displaying errors to users or logging. Will be None if task has not failed or if no error details are available. Serialized as 'error' in API responses for backward compatibility.","examples":["Failed to process batch: Object not found","Invalid file format: Expected PDF, got PNG","Clustering failed: Insufficient data points",null]}},"type":"object","required":["task_id","task_type","status"],"title":"TaskResponse","description":"Task response model returned by the API.\n\nExtends TaskModel with additional convenience fields for API responses.\nThis is the model returned when you GET /v1/tasks/{task_id}.\n\nAdditional Fields:\n error_message: Convenience field that surfaces errors from additional_data\n for easier error handling in client code.\n\nInheritance:\n Inherits all fields and documentation from TaskModel, including:\n - task_id: Unique identifier\n - task_type: Operation type\n - status: Current status\n - inputs: Input parameters\n - outputs: Output results\n - additional_data: Metadata and context\n\nStorage Architecture:\n Same as TaskModel - stored in Redis (24hr TTL) with MongoDB fallback.\n\nUsage:\n This model is automatically returned by task API endpoints. You don't\n need to construct it manually - just call GET /v1/tasks/{task_id}.\n\nError Handling:\n Check the error_message field for a user-friendly error string, or\n additional_data['error'] for the full error details.\n\nExample Response:\n {\n \"task_id\": \"task_abc123\",\n \"task_type\": \"api_buckets_batches_process\",\n \"status\": \"FAILED\",\n \"inputs\": [\"batch_xyz\"],\n \"outputs\": null,\n \"additional_data\": {\n \"error\": \"Failed to process batch: Object not found\",\n \"batch_id\": \"batch_xyz\"\n },\n \"error_message\": \"Failed to process batch: Object not found\"\n }","examples":[{"additional_data":{"batch_id":"btch_xyz789","bucket_id":"bkt_products","collection_ids":["col_tier0","col_tier1","col_tier2"],"current_tier":1,"job_id":"ray_job_123","namespace_id":"ns_abc123","object_count":10000,"sample_object_ids":["obj_001","obj_002","obj_003","obj_004","obj_005"],"total_tiers":3},"description":"Multi-tier batch processing task in progress (tier 1 of 3) with 10k objects","inputs":["batch_xyz789"],"status":"IN_PROGRESS","task_id":"2d322a05-3178-4eca-aac6-b82b0a0313aa","task_type":"api_buckets_batches_process"},{"additional_data":{"cluster_id":"cl_abc123","job_id":"ray_job_456"},"description":"Completed clustering task with results","inputs":[{"collection_ids":["col_products"],"config":{"algorithm":"kmeans","k":5}}],"outputs":[{"cluster_id":"cl_abc123","num_clusters":5,"silhouette_score":0.78}],"status":"COMPLETED","task_id":"task_cluster_789","task_type":"engine_cluster_build"},{"additional_data":{"bucket_id":"bkt_test","error":"Invalid file format: Expected PDF, got PNG","object_id":"obj_123"},"description":"Failed object creation task with error","inputs":[{"bucket_id":"bkt_test","object_id":"obj_123"}],"status":"FAILED","task_id":"task_failed_123","task_type":"api_buckets_objects_create"},{"additional_data":{"batch_id":"batch_old_123","from_mongodb":true,"note":"Retrieved from persistent storage after 24hr Redis expiry"},"description":"Task retrieved from MongoDB fallback (Redis expired)","inputs":["batch_old_123"],"outputs":["Processed 500 objects"],"status":"COMPLETED","task_id":"taYOUR_OLD_API_KEY","task_type":"api_buckets_batches_process"}]},"TaskStatusEnum":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSING","COMPLETED","COMPLETED_WITH_ERRORS","FAILED","CANCELED","UNKNOWN","SKIPPED","DRAFT","ACTIVE","ARCHIVED","SUSPENDED"],"title":"TaskStatusEnum","description":"Enumeration of task statuses for tracking asynchronous operations.\n\nTask statuses indicate the current state of asynchronous operations like\nbatch processing, object ingestion, clustering, and taxonomy execution.\n\nStatus Categories:\n Operation Statuses: Track progress of async operations\n Lifecycle Statuses: Track entity state (buckets, collections, namespaces)\n\nValues:\n PENDING: Task is queued but has not started processing yet\n IN_PROGRESS: Task is currently being executed\n PROCESSING: Task is actively processing data (similar to IN_PROGRESS)\n COMPLETED: Task finished successfully with no errors\n COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success)\n FAILED: Task encountered an error and could not complete\n CANCELED: Task was manually canceled by a user or system\n UNKNOWN: Task status could not be determined\n SKIPPED: Task was intentionally skipped\n DRAFT: Task is in draft state and not yet submitted\n\n ACTIVE: Entity is active and operational (for buckets, collections, etc.)\n ARCHIVED: Entity has been archived\n SUSPENDED: Entity has been temporarily suspended\n\nTerminal Statuses:\n COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses.\n Once a task reaches these states, it will not transition to another state.\n\nPartial Success Handling:\n COMPLETED_WITH_ERRORS indicates that the operation completed but some\n documents/items failed. The task result includes:\n - List of successful items\n - List of failed items with error details\n - Success rate percentage\n This allows clients to handle partial success scenarios appropriately.\n\nPolling Guidance:\n - Poll tasks in PENDING, IN_PROGRESS, or PROCESSING states\n - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED\n - Use exponential backoff (1s ā†’ 30s) when polling"},"TaskStatusUpdateRequest":{"properties":{"internal_id":{"type":"string","title":"Internal Id"},"namespace_id":{"type":"string","title":"Namespace Id"},"status":{"type":"string","title":"Status"},"outputs":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Outputs"},"additional_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Additional Data"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["internal_id","namespace_id","status"],"title":"TaskStatusUpdateRequest","description":"Request to update task status (Engine callback)."},"TaskType":{"type":"string","enum":["api_namespaces_create","api_namespaces_delete","api_namespaces_migrations_run","api_buckets_objects_create","api_buckets_delete","api_buckets_batches_process","api_buckets_batches_submit","api_buckets_uploads_create","api_buckets_uploads_confirm","api_buckets_uploads_batch_confirm","api_collections_documents_create","api_collections_extraction_artifacts","api_taxonomies_create","api_taxonomies_execute","api_taxonomies_materialize","api_evaluations_run","api_evaluations_dataset_create","api_retrievers_publish","api_collections_export","api_collections_trigger","engine_feature_extractor_run","engine_inference_run","engine_object_processing","engine_cluster_build","thumbnail","video_segment","audio_segment","materialize","plugin_custom","model_custom"],"title":"TaskType","description":"Types of asynchronous tasks that can be performed in the system.\n\nTask types identify the specific operation being performed. This helps with\ntracking, debugging, and filtering tasks by operation type.\n\nCategories:\n API Tasks: User-initiated operations via API endpoints\n Engine Tasks: Background processing tasks\n Inference Tasks: Specialized inference operations\n\nAPI Task Types:\n API_NAMESPACES_CREATE: Creating a new namespace\n API_NAMESPACES_MIGRATIONS_RUN: Running a namespace migration\n API_BUCKETS_OBJECTS_CREATE: Creating objects in a bucket\n API_BUCKETS_DELETE: Deleting a bucket and its contents\n API_BUCKETS_BATCHES_PROCESS: Processing a batch of objects\n API_BUCKETS_BATCHES_SUBMIT: Submitting a batch for processing\n API_BUCKETS_UPLOADS_CREATE: Creating an upload session\n API_BUCKETS_UPLOADS_CONFIRM: Confirming an upload completion\n API_BUCKETS_UPLOADS_BATCH_CONFIRM: Confirming batch upload completion\n API_TAXONOMIES_CREATE: Creating a new taxonomy\n API_TAXONOMIES_EXECUTE: Executing taxonomy classification\n API_TAXONOMIES_MATERIALIZE: Materializing taxonomy results\n API_RETRIEVERS_PUBLISH: Publishing retriever assets (OG images, etc.)\n\nEngine Task Types:\n ENGINE_FEATURE_EXTRACTOR_RUN: Running feature extraction on data\n ENGINE_INFERENCE_RUN: Running inference operations\n ENGINE_OBJECT_PROCESSING: Processing object data\n ENGINE_CLUSTER_BUILD: Building clusters from data\n\nInference Task Types:\n THUMBNAIL: Generating thumbnails\n MATERIALIZE: Materializing processed data\n\nUsage:\n Task types are automatically assigned when tasks are created. You can\n filter tasks by type when listing or searching for specific operations."},"TaxonomyApplicationConfig-Input":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"ID of the `TaxonomyModel` to execute."},"execution_mode":{"$ref":"#/components/schemas/TaxonomyExecutionMode","description":"Execution mode for taxonomy enrichment. Materializes results during ingestion.","default":"materialize"},"target_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Collection Id","description":"Optional collection to persist results into when `execution_mode` is 'materialize'. If omitted, the source collection is updated in-place."},"scroll_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Additional filters applied when scrolling the source collection before enrichment."},"execution_phase":{"type":"integer","maximum":3.0,"minimum":1.0,"title":"Execution Phase","description":"Which phase this taxonomy runs in. Default: 1 (TAXONOMY phase, runs first). Valid values: 1=TAXONOMY, 2=CLUSTER, 3=ALERT. Lower phases run earlier.","default":1},"priority":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Priority","description":"Priority within the execution phase (higher = runs first)","default":0},"hierarchical_enrichment_style":{"$ref":"#/components/schemas/HierarchicalEnrichmentStyle","description":"For hierarchical taxonomies, controls how enrichment fields are structured. 'full_chain': Each tier writes to tier-prefixed fields (tier1_id, tier2_id, etc.). 'best_match': Only deepest match stored (category_id, category_name, path[]). 'combined' (default): Both full chain AND best match summary fields.","default":"combined"}},"additionalProperties":false,"type":"object","required":["taxonomy_id"],"title":"TaxonomyApplicationConfig","description":"Configuration block that attaches a taxonomy to a collection.\n\nSupports execution phase ordering for unified post-processing with\ntaxonomies, clusters, and alerts.","examples":[{"execution_mode":"materialize","taxonomy_id":"tax_abc123"},{"execution_mode":"materialize","execution_phase":1,"priority":10,"target_collection_id":"col_enriched_v1","taxonomy_id":"tax_abc123"},{"execution_mode":"materialize","hierarchical_enrichment_style":"full_chain","taxonomy_id":"tax_iab_content"}]},"TaxonomyApplicationConfig-Output":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"ID of the `TaxonomyModel` to execute."},"execution_mode":{"$ref":"#/components/schemas/TaxonomyExecutionMode","description":"Execution mode for taxonomy enrichment. Materializes results during ingestion.","default":"materialize"},"target_collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Collection Id","description":"Optional collection to persist results into when `execution_mode` is 'materialize'. If omitted, the source collection is updated in-place."},"scroll_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Output"},{"type":"null"}],"description":"Additional filters applied when scrolling the source collection before enrichment."},"execution_phase":{"type":"integer","maximum":3.0,"minimum":1.0,"title":"Execution Phase","description":"Which phase this taxonomy runs in. Default: 1 (TAXONOMY phase, runs first). Valid values: 1=TAXONOMY, 2=CLUSTER, 3=ALERT. Lower phases run earlier.","default":1},"priority":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Priority","description":"Priority within the execution phase (higher = runs first)","default":0},"hierarchical_enrichment_style":{"$ref":"#/components/schemas/HierarchicalEnrichmentStyle","description":"For hierarchical taxonomies, controls how enrichment fields are structured. 'full_chain': Each tier writes to tier-prefixed fields (tier1_id, tier2_id, etc.). 'best_match': Only deepest match stored (category_id, category_name, path[]). 'combined' (default): Both full chain AND best match summary fields.","default":"combined"}},"additionalProperties":false,"type":"object","required":["taxonomy_id"],"title":"TaxonomyApplicationConfig","description":"Configuration block that attaches a taxonomy to a collection.\n\nSupports execution phase ordering for unified post-processing with\ntaxonomies, clusters, and alerts.","examples":[{"execution_mode":"materialize","taxonomy_id":"tax_abc123"},{"execution_mode":"materialize","execution_phase":1,"priority":10,"target_collection_id":"col_enriched_v1","taxonomy_id":"tax_abc123"},{"execution_mode":"materialize","hierarchical_enrichment_style":"full_chain","taxonomy_id":"tax_iab_content"}]},"TaxonomyExecutionMode":{"type":"string","enum":["materialize"],"title":"TaxonomyExecutionMode","description":"How a taxonomy should be executed when attached to a collection."},"TaxonomyListStats":{"properties":{"total_taxonomies":{"type":"integer","title":"Total Taxonomies","description":"Total number of taxonomies in the result","default":0},"flat_taxonomies":{"type":"integer","title":"Flat Taxonomies","description":"Number of flat taxonomies","default":0},"hierarchical_taxonomies":{"type":"integer","title":"Hierarchical Taxonomies","description":"Number of hierarchical taxonomies","default":0},"taxonomies_with_retrievers":{"type":"integer","title":"Taxonomies With Retrievers","description":"Number of taxonomies with retriever configured","default":0}},"type":"object","title":"TaxonomyListStats","description":"Aggregate statistics for a list of taxonomies."},"TaxonomyModel-Input":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"Unique identifier for the taxonomy"},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Monotonic version number of the taxonomy configuration","default":1},"taxonomy_name":{"type":"string","title":"Taxonomy Name","description":"A unique name for the taxonomy within the namespace."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional human-readable description."},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Optional taxonomy-level retriever (prefer per-layer)."},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"Optional taxonomy-level inputs (prefer per-layer)."},"config":{"oneOf":[{"$ref":"#/components/schemas/FlatTaxonomyConfig-Input"},{"$ref":"#/components/schemas/HierarchicalTaxonomyConfig-Input"}],"title":"Config","description":"Configuration specific to the taxonomy type.","discriminator":{"propertyName":"taxonomy_type","mapping":{"flat":"#/components/schemas/FlatTaxonomyConfig-Input","hierarchical":"#/components/schemas/HierarchicalTaxonomyConfig-Input"}}},"ready":{"type":"boolean","title":"Ready","description":"Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp for this taxonomy record"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional user-defined metadata for the taxonomy"}},"type":"object","required":["taxonomy_name","config"],"title":"TaxonomyModel","description":"Primary Pydantic model representing a taxonomy definition.","examples":[{"config":{"default_input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"default_retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1"},"taxonomy_type":"flat"},"namespace_id":"ns_123","taxonomy_name":"product_tags","taxonomy_type":"flat"},{"config":{"build_mode":"explicit","default_input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"default_retriever_id":"ret_face_v1","hierarchical_nodes":[{"collection_id":"col_employees_v1"},{"collection_id":"col_executives_v1","parent_collection_id":"col_employees_v1"}],"taxonomy_type":"hierarchical"},"namespace_id":"ns_123","taxonomy_name":"org_hierarchy","taxonomy_type":"hierarchical"}]},"TaxonomyModel-Output":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"Unique identifier for the taxonomy"},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Monotonic version number of the taxonomy configuration","default":1},"taxonomy_name":{"type":"string","title":"Taxonomy Name","description":"A unique name for the taxonomy within the namespace."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional human-readable description."},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Optional taxonomy-level retriever (prefer per-layer)."},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"Optional taxonomy-level inputs (prefer per-layer)."},"config":{"oneOf":[{"$ref":"#/components/schemas/FlatTaxonomyConfig-Output"},{"$ref":"#/components/schemas/HierarchicalTaxonomyConfig-Output"}],"title":"Config","description":"Configuration specific to the taxonomy type.","discriminator":{"propertyName":"taxonomy_type","mapping":{"flat":"#/components/schemas/FlatTaxonomyConfig-Output","hierarchical":"#/components/schemas/HierarchicalTaxonomyConfig-Output"}}},"ready":{"type":"boolean","title":"Ready","description":"Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp for this taxonomy record"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional user-defined metadata for the taxonomy"}},"type":"object","required":["taxonomy_name","config"],"title":"TaxonomyModel","description":"Primary Pydantic model representing a taxonomy definition.","examples":[{"config":{"default_input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"default_retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1"},"taxonomy_type":"flat"},"namespace_id":"ns_123","taxonomy_name":"product_tags","taxonomy_type":"flat"},{"config":{"build_mode":"explicit","default_input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"default_retriever_id":"ret_face_v1","hierarchical_nodes":[{"collection_id":"col_employees_v1"},{"collection_id":"col_executives_v1","parent_collection_id":"col_employees_v1"}],"taxonomy_type":"hierarchical"},"namespace_id":"ns_123","taxonomy_name":"org_hierarchy","taxonomy_type":"hierarchical"}]},"TaxonomyOptions":{"properties":{"preserve_taxonomy_ids":{"type":"boolean","title":"Preserve Taxonomy Ids","description":"Keep same taxonomy IDs in target","default":true},"preserve_enrichment_fields":{"type":"boolean","title":"Preserve Enrichment Fields","description":"Keep _taxonomy_* fields in documents","default":true},"re_run_enrichment":{"type":"boolean","title":"Re Run Enrichment","description":"Re-run taxonomy enrichment after migration","default":false},"migrate_reference_collections":{"type":"boolean","title":"Migrate Reference Collections","description":"Automatically migrate reference collections","default":true}},"type":"object","title":"TaxonomyOptions","description":"Options for taxonomy migration."},"TaxonomyResponse":{"properties":{"taxonomy_id":{"type":"string","title":"Taxonomy Id","description":"Unique identifier for the taxonomy"},"version":{"type":"integer","minimum":1.0,"title":"Version","description":"Monotonic version number of the taxonomy configuration","default":1},"taxonomy_name":{"type":"string","title":"Taxonomy Name","description":"A unique name for the taxonomy within the namespace."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional human-readable description."},"retriever_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retriever Id","description":"Optional taxonomy-level retriever (prefer per-layer)."},"input_mappings":{"anyOf":[{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"},{"type":"null"}],"title":"Input Mappings","description":"Optional taxonomy-level inputs (prefer per-layer)."},"config":{"oneOf":[{"$ref":"#/components/schemas/FlatTaxonomyConfig-Output"},{"$ref":"#/components/schemas/HierarchicalTaxonomyConfig-Output"}],"title":"Config","description":"Configuration specific to the taxonomy type.","discriminator":{"propertyName":"taxonomy_type","mapping":{"flat":"#/components/schemas/FlatTaxonomyConfig-Output","hierarchical":"#/components/schemas/HierarchicalTaxonomyConfig-Output"}}},"ready":{"type":"boolean","title":"Ready","description":"Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp for this taxonomy record"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional user-defined metadata for the taxonomy"}},"type":"object","required":["taxonomy_name","config"],"title":"TaxonomyResponse","description":"Response model for a taxonomy.","examples":[{"config":{"default_input_mappings":[{"input_key":"image_vector","path":"features.clip_vit_l_14","source_type":"vector"}],"default_retriever_id":"ret_clip_v1","source_collection":{"collection_id":"col_products_v1"},"taxonomy_type":"flat"},"namespace_id":"ns_123","taxonomy_name":"product_tags","taxonomy_type":"flat"},{"config":{"build_mode":"explicit","default_input_mappings":[{"input_key":"face_vec","path":"features.face","source_type":"vector"}],"default_retriever_id":"ret_face_v1","hierarchical_nodes":[{"collection_id":"col_employees_v1"},{"collection_id":"col_executives_v1","parent_collection_id":"col_employees_v1"}],"taxonomy_type":"hierarchical"},"namespace_id":"ns_123","taxonomy_name":"org_hierarchy","taxonomy_type":"hierarchical"}]},"TemplateMode":{"type":"string","enum":["scaffold","config","clone"],"title":"TemplateMode","description":"Mode of template instantiation.\n\nscaffold: Create from pre-built preset\n - Creates: namespace + bucket + collection + retriever\n - Endpoint: POST /templates/scaffolds/{id}/instantiate\n - All resources empty, ready for data\n\nconfig: Copy resource configuration only\n - Creates: empty resource with same settings\n - Endpoint: POST /templates/{resource}/{id}/instantiate\n - No data copied\n\nclone: Copy resource with all data\n - Creates: full copy including vectors/embeddings\n - Endpoint: POST /namespaces/{id}/clone\n - For config-only, use templates instead"},"TemplateScope":{"type":"string","enum":["system","organization","user","public"],"title":"TemplateScope","description":"Scope of template availability.\n\nsystem: Mixpeek-provided, available to all orgs\norganization: Private to org members\nuser: Private to creator only\npublic: User-created, discoverable by all orgs (marketplace)"},"TemplateType":{"type":"string","enum":["namespace","retriever","cluster","collection","bucket","taxonomy","scaffold"],"title":"TemplateType","description":"Types of resources that can be templated."},"TerminateSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Session identifier"},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Session status (terminated)"},"terminated_at":{"type":"string","format":"date-time","title":"Terminated At","description":"Termination timestamp"}},"type":"object","required":["session_id","status","terminated_at"],"title":"TerminateSessionResponse","description":"Response for session termination.\n\nAttributes:\n session_id: Session identifier\n status: New session status (terminated)\n terminated_at: Termination timestamp"},"TextExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"text_extractor","title":"Extractor Type","description":"Discriminator field for parameter type identification.","default":"text_extractor"},"source_type":{"type":"string","enum":["text","youtube"],"title":"Source Type","description":"Source content type. Use 'youtube' to resolve YouTube URLs to caption text before embedding. Default: 'text' (plain text input).","default":"text"},"split_by":{"$ref":"#/components/schemas/TextSplitStrategy","description":"Strategy for splitting text into multiple documents.","default":"none"},"chunk_size":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Chunk Size","description":"Target size for each chunk.","default":1000},"chunk_overlap":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Chunk Overlap","description":"Number of units to overlap between consecutive chunks.","default":0},"segment_length_seconds":{"type":"integer","maximum":600.0,"minimum":30.0,"title":"Segment Length Seconds","description":"Length of each transcript segment in seconds (for time_segments split strategy). Shorter segments give more precise search results but more documents.","default":120},"language":{"type":"string","title":"Language","description":"Preferred language code for YouTube captions (when source_type='youtube').","default":"en"},"extract_captions":{"type":"boolean","title":"Extract Captions","description":"Extract auto-captions or manual subtitles from YouTube videos (when source_type='youtube'). Falls back to video description if False.","default":true},"response_shape":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Shape","description":"Define custom structured output using LLM extraction."},"llm_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Provider","description":"LLM provider for structured extraction (openai, google, anthropic)."},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model","description":"Specific LLM model for structured extraction."},"llm_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Api Key","description":"API key for LLM operations (BYOK - Bring Your Own Key). Supports:\n- Direct key: 'sk-proj-abc123...'\n- Secret reference: '{{SECRET.openai_api_key}}'\n\nWhen using secret reference, the key is loaded from your organization's secrets vault at runtime. Store secrets via POST /v1/organizations/secrets.\n\nIf not provided, uses Mixpeek's default API keys."}},"type":"object","title":"TextExtractorParams","description":"Parameters for the text extractor.\n\nThe text extractor generates dense vector embeddings optimized for semantic similarity search.\nIt uses the E5-Large multilingual model to convert text into 1024-dimensional vectors.\n\nWhen ``source_type`` is ``\"youtube\"``, the extractor first resolves YouTube URLs\nto caption text via yt-dlp before chunking and embedding. Use ``split_by=\"time_segments\"``\nwith ``segment_length_seconds`` to segment captions by time window.","examples":[{"chunk_overlap":0,"chunk_size":1000,"extractor_type":"text_extractor","split_by":"none"},{"chunk_overlap":1,"chunk_size":5,"extractor_type":"text_extractor","split_by":"sentences"},{"extractor_type":"text_extractor","language":"en","segment_length_seconds":120,"source_type":"youtube","split_by":"time_segments"}]},"TextIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"text"},"tokenizer":{"$ref":"#/components/schemas/TokenizerType","default":"word"},"min_token_len":{"type":"integer","title":"Min Token Len","default":2},"max_token_len":{"type":"integer","title":"Max Token Len","default":15},"lowercase":{"type":"boolean","title":"Lowercase","default":true}},"type":"object","title":"TextIndexParams","description":"Configuration for text index."},"TextSplitStrategy":{"type":"string","enum":["characters","words","sentences","paragraphs","pages","time_segments","none"],"title":"TextSplitStrategy","description":"Strategy for splitting text into chunks."},"ThemeConfig":{"properties":{"primary_color":{"type":"string","title":"Primary Color","description":"Primary brand color (hex code)","default":"#007AFF","examples":["#007AFF","#FF6B6B","#4ECDC4"]},"secondary_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secondary Color","description":"Secondary/accent color (hex code)","examples":["#FF6B6B","#95E1D3"]},"font_family":{"type":"string","title":"Font Family","description":"Font family for text","default":"system-ui, -apple-system, sans-serif","examples":["Inter, sans-serif","Roboto, sans-serif"]},"background_color":{"type":"string","title":"Background Color","description":"Background color (hex code)","default":"#FFFFFF"},"text_color":{"type":"string","title":"Text Color","description":"Primary text color (hex code)","default":"#374151"},"heading_font_family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading Font Family","description":"Optional separate font family for headings","examples":["Georgia, serif","Playfair Display, serif"]},"surface_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Surface Color","description":"Surface/card background color (hex code)","examples":["#F9FAFB","#F3F4F6"]},"muted_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Muted Color","description":"Muted/secondary text color (hex code)","examples":["#6B7280","#9CA3AF"]},"border_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Border Color","description":"Border color for cards and elements (hex code)","examples":["#E5E7EB","#D1D5DB"]},"border_radius":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Border Radius","description":"Default border radius for cards and elements","default":"12px","examples":["8px","12px","16px","24px"]},"card_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Style","description":"Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)","default":"elevated","examples":["elevated","flat","bordered","glass"]},"card_hover_effect":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Hover Effect","description":"Card hover animation effect: lift (move up), glow, scale, or none","default":"lift","examples":["lift","glow","scale","none"]}},"type":"object","title":"ThemeConfig","description":"Theme configuration for public retriever UI.\n\nDefines colors, fonts, and visual styling for the public search interface."},"TierDiagnostic":{"properties":{"tier_num":{"type":"integer","title":"Tier Num","description":"Tier number"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Task ID for this tier"},"status":{"type":"string","title":"Status","description":"Tier status (PENDING, PROCESSING, COMPLETED, FAILED)"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When tier started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When tier completed"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Duration in seconds"},"progress":{"anyOf":[{"$ref":"#/components/schemas/TaskProgress"},{"type":"null"}],"description":"Progress information"},"ray_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Job Id","description":"Ray job ID"},"ray_dashboard_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Dashboard Url","description":"Link to Ray dashboard"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"},"error_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Type","description":"Error type if failed"}},"type":"object","required":["tier_num","status"],"title":"TierDiagnostic","description":"Diagnostic information for a single tier."},"TierLimits":{"properties":{"requests_per_minute":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests Per Minute","description":"Maximum requests per minute (None = unlimited)"},"requests_per_hour":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests Per Hour","description":"Maximum requests per hour (None = unlimited)"},"requests_per_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests Per Day","description":"Maximum requests per day (None = unlimited)"},"requests_per_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests Per Month","description":"Maximum requests per month (None = unlimited)"}},"type":"object","title":"TierLimits","description":"Rate limits and quotas for a subscription tier."},"TierTaskInfo":{"properties":{"tier_num":{"type":"integer","minimum":0.0,"title":"Tier Num","description":"REQUIRED. Zero-based tier number indicating the processing stage. Tier 0 = initial bucket-to-collection processing (bucket objects as source). Tier N (N > 0) = collection-to-collection processing (upstream documents as source). Used to determine processing order and identify which stage a task represents. Example: In a 5-tier pipeline (bucket ā†’ chunks ā†’ frames ā†’ scenes ā†’ summaries), chunks=tier 0, frames=tier 1, scenes=tier 2, summaries=tier 3.","examples":[0,1,2]},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"OPTIONAL. Unique task identifier for this tier's processing task. None if tier has not yet started (status=PENDING). Assigned when tier processing begins (status=IN_PROGRESS). Used to query task status via GET /v1/tasks/{task_id}. Format: 'task_' prefix followed by secure token. Generated using generate_secure_token() from shared.utilities.helpers.","examples":["task_tier0_abc123","task_tier1_def456","task_tier2_ghi789"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"REQUIRED. Current processing status of this tier's task. Lifecycle: PENDING ā†’ IN_PROGRESS ā†’ COMPLETED/FAILED. PENDING: Tier scheduled but not yet started. IN_PROGRESS: Tier currently processing documents. COMPLETED: Tier successfully processed all documents. FAILED: Tier encountered an error and stopped processing. Used to determine overall batch status and whether to proceed to next tier.","default":"PENDING","examples":["PENDING","IN_PROGRESS","COMPLETED","FAILED"]},"collection_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Collection Ids","description":"REQUIRED. List of collection IDs being processed in this tier. Flattened from extractor_jobs for convenience. Each tier can process one or more collections in parallel. Collections in the same tier have no dependencies on each other. Format: Collection IDs as defined when collections were created. Minimum 1 collection per tier. Example: Tier 1 might process ['col_frames_30fps', 'col_frames_60fps'] in parallel.","examples":[["col_chunks"],["col_frames","col_scenes"],["col_summaries"]]},"extractor_jobs":{"items":{"$ref":"#/components/schemas/ExtractorJobInfo"},"type":"array","title":"Extractor Jobs","description":"List of extractor jobs for this tier (one per unique feature_extractor_type). NEW as of 2025-12-31: Tiers now support multiple Ray jobs. Empty list for backwards compatibility with old batches. Tier completes when ALL extractor_jobs reach COMPLETED status."},"source_type":{"type":"string","title":"Source Type","description":"REQUIRED. Type of data source for this tier's processing. 'bucket': Tier 0 processing where source is bucket objects from the objects table. 'collection': Tier N+ processing where source is documents from upstream collection(s). Determines how the API prepares the input dataset manifest for the Engine. Bucket sources query the objects table and include file blobs. Collection sources query the documents table and include processed features.","examples":["bucket","collection"]},"source_collection_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Source Collection Ids","description":"OPTIONAL for tier 0 (must be None). REQUIRED for tier N+ (N > 0). List of upstream collection IDs that provide documents as input to this tier. Typically contains collection IDs from the previous tier (tier_num - 1). Used by the API to query documents from these collections for processing. These upstream documents are converted to a Parquet manifest for the Engine. Example: If tier 1 processes 'col_frames' and sources from tier 0's 'col_chunks', then source_collection_ids=['col_chunks'].","examples":[["col_chunks"],["col_frames"],["col_scenes","col_objects"]]},"parent_task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Task Id","description":"OPTIONAL. Task ID of the previous tier (tier_num - 1) that processed before this tier. Used to link tiers together for audit trail and lineage tracking. None for tier 0 (no parent). Enables queries like 'show all tiers that processed after tier 0' or 'trace back through all parent tiers to find the original batch'. Format: Same as task_id (e.g., 'task_tier0_abc123').","examples":["task_tier0_abc123","task_tier1_def456"]},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"OPTIONAL. ISO 8601 timestamp when this tier began processing. None if tier has not yet started (status=PENDING). Set using current_time() from shared.utilities.helpers when tier starts. Used to calculate tier processing duration and identify long-running tiers. Example: '2025-11-03T10:00:00Z'.","examples":["2025-11-03T10:00:00Z","2025-11-03T14:30:15Z"]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"OPTIONAL. ISO 8601 timestamp when this tier finished processing (success or failure). None if tier has not yet completed (status=PENDING or IN_PROGRESS). Set using current_time() from shared.utilities.helpers when tier completes. Used to calculate tier processing duration (completed_at - started_at). Set for both COMPLETED and FAILED statuses. Example: '2025-11-03T10:05:00Z'.","examples":["2025-11-03T10:05:00Z","2025-11-03T14:35:42Z"]},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms","description":"OPTIONAL. Processing duration in milliseconds for this tier. Calculated as (completed_at - started_at) when tier completes. None if tier has not yet completed or if started_at was not set. Provides a pre-computed duration for easy querying without timestamp math. Set for both COMPLETED and FAILED statuses.","examples":[300000.0,5000.5,12345.67]},"errors":{"items":{"$ref":"#/components/schemas/BatchErrorDetail"},"type":"array","title":"Errors","description":"OPTIONAL. List of detailed errors that occurred during tier processing. Empty list if tier succeeded or has not yet completed. Each error includes: error_type, message, component, stage, traceback, timestamp. Multiple errors may occur if different documents fail with different issues. Used for detailed error analysis, debugging, and intelligent retry logic. Example: Multiple documents failing with different errors (dependency vs auth). For backward compatibility, check if list is empty for success/in-progress status.","examples":[[],[{"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":10,"component":"VertexMultimodalService","error_type":"authentication","message":"Invalid Vertex AI credentials"},{"affected_count":3,"component":"GeminiExtractor","error_type":"validation","message":"Schema validation failed"}]]},"error_summary":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Error Summary","description":"OPTIONAL. Aggregated summary of errors by error type. None if tier succeeded or has not yet completed. Maps error_type (category) to count of affected documents. Provides quick overview of error distribution without parsing full error list. Example: {'dependency': 5, 'authentication': 10, 'validation': 3} means 5 documents failed with dependency errors, 10 with auth errors, 3 with validation. Automatically generated from errors list for convenience. Used for batch health monitoring and error trend analysis.","examples":[null,{"dependency":5},{"authentication":10,"runtime":2,"validation":3}]},"performance":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Performance","description":"OPTIONAL. Performance metrics summary for this tier's execution. Automatically populated after tier completion by collecting data from ClickHouse analytics. Contains: total_time_ms (total execution time), avg_latency_ms (average operation latency), bottlenecks (list of slowest operations), stage_count (number of profiled stages). Used for troubleshooting performance issues and identifying bottlenecks. None if tier has not completed or performance data collection failed. Populated asynchronously via Celery task (non-blocking, best-effort).","examples":[{"avg_latency_ms":234.56,"bottlenecks":[{"avg_time_ms":113.58,"execution_count":50,"max_time_ms":234.56,"stage_name":"gcs_batch_upload_all_segments","total_time_ms":5678.9},{"avg_time_ms":69.14,"execution_count":50,"max_time_ms":123.45,"stage_name":"pipeline_run","total_time_ms":3456.78}],"stage_count":5,"timestamp":"2025-11-06T10:05:00Z","total_time_ms":12345.67}]},"ray_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ray Job Id","description":"OPTIONAL. Ray/Anyscale job ID for tracking the infrastructure-level processing job. None if tier has not yet started or if the job ID was not returned by the engine. Set when tier processing is submitted to Ray/Anyscale via the Engine. Used for cancelling running jobs and monitoring infrastructure-level status. Format: 'raysubmit_' prefix followed by job identifier (e.g., 'raysubmit_9pDAyZbd5MN281TB'). This is the job ID that appears in the Ray/Anyscale dashboard.","examples":["raysubmit_9pDAyZbd5MN281TB","raysubmit_ABC123XYZ456"]},"celery_task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Celery Task Id","description":"OPTIONAL. Celery task ID for tracking the Celery worker processing this tier. None if tier has not yet started or is not processed via Celery. Set when process_tier Celery task is triggered. Used for revoking pending/running Celery tasks during batch cancellation or deletion. Format: UUID string (e.g., 'a1b2c3d4-e5f6-7890-abcd-ef1234567890').","examples":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]},"source_documents_fetched":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Documents Fetched","description":"OPTIONAL. Number of documents fetched from source collection(s) for Tier N processing. For Tier 0 (bucket source), this is the number of objects from the bucket. For Tier N+ (collection source), this is the count of documents from upstream collection(s). Set at the start of tier artifact building in build_tier_n_artifacts(). If 0, the source collection is empty - check upstream tier completion.","examples":[100,0,1500]},"documents_after_source_filter":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents After Source Filter","description":"OPTIONAL. Number of documents remaining after applying source_filters. source_filters are optional conditions that exclude documents from processing. If this is 0 but source_documents_fetched > 0, your source_filters are too restrictive. Check that filter fields exist in source documents and conditions match expected values.","examples":[95,0,1200]},"documents_missing_input_fields":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Missing Input Fields","description":"OPTIONAL. Number of documents missing required input_mapping fields. input_mappings define which fields from source documents map to extractor inputs. If this equals documents_after_source_filter, ALL documents are missing required fields. Common cause: upstream extractor didn't produce expected output (e.g., video_segment_url). Check upstream extractor configuration and verify output field names.","examples":[0,95,50]},"documents_submitted_to_engine":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Submitted To Engine","description":"OPTIONAL. Number of documents actually submitted to the Ray/Engine for processing. This is documents_after_source_filter minus documents_missing_input_fields. If 0, no documents were sent to the engine - check source_filters and input_mappings. If > 0 but documents_written = 0, the engine failed to process documents.","examples":[95,0,1150]},"documents_written":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Written","description":"OPTIONAL. Total document count in target collection(s) after processing. Set after tier completion by querying the collection document count. Compare with documents_before_processing to get the delta (new docs created). If 0 but documents_submitted_to_engine > 0, check tier errors for processing failures.","examples":[95,0,1150]},"documents_before_processing":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Documents Before Processing","description":"OPTIONAL. Document count in target collection(s) before this tier started processing. Compare (documents_written - documents_before_processing) to get the number of NEW documents created by this batch tier. A delta of 0 means all objects were already processed (deduplication) or all failed silently.","examples":[0,50,1000]}},"type":"object","required":["tier_num","source_type"],"title":"TierTaskInfo","description":"Tracking information for a single collection processing tier's task.\n\nIn multi-tier collection processing, each tier represents a processing stage in the\ndecomposition pipeline (e.g., bucket ā†’ chunks ā†’ frames ā†’ scenes). Each tier gets its\nown independent task for granular monitoring, status tracking, and retry capabilities.\n\nUse Cases:\n - Monitor progress of individual tiers in a multi-tier batch\n - Retry failed tiers without reprocessing successful ones\n - Track lineage of processing through parent_task_id linkage\n - Query task status for specific processing stages\n\nTier Definitions:\n - Tier 0: Bucket ā†’ Collection (bucket objects as source)\n - Tier N (N > 0): Collection ā†’ Collection (upstream collection documents as source)\n\nLifecycle:\n 1. Created with status=PENDING when tier is scheduled\n 2. Updated to status=IN_PROGRESS when processing starts (task_id assigned)\n 3. Finalized to status=COMPLETED or status=FAILED when tier completes\n\nRequirements:\n - tier_num: REQUIRED. Zero-based tier number indicating processing stage\n - task_id: OPTIONAL. None until tier processing starts\n - status: REQUIRED. Defaults to PENDING\n - collection_ids: REQUIRED. Collections being processed in this tier\n - source_type: REQUIRED. \"bucket\" for tier 0, \"collection\" for tier N+\n - source_collection_ids: OPTIONAL. Required for tier N+ (collection sources)\n - parent_task_id: OPTIONAL. Links to previous tier for audit trail\n - started_at: OPTIONAL. Set when tier processing begins\n - completed_at: OPTIONAL. Set when tier processing finishes\n - error: OPTIONAL. Set if tier fails with error details","examples":[{"collection_ids":["col_chunks"],"completed_at":"2025-11-03T10:05:00Z","description":"Tier 0 task (completed): Bucket ā†’ Collection","errors":[],"ray_job_id":"raysubmit_ABC123","source_type":"bucket","started_at":"2025-11-03T10:00:00Z","status":"COMPLETED","task_id":"task_tier0_abc123","tier_num":0},{"collection_ids":["col_frames"],"description":"Tier 1 task (in progress): Collection ā†’ Collection","errors":[],"parent_task_id":"task_tier0_abc123","ray_job_id":"raysubmit_DEF456","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"],"description":"Tier 2 task (pending): Not yet started","errors":[],"source_collection_ids":["col_frames"],"source_type":"collection","status":"PENDING","tier_num":2},{"collection_ids":["col_frames"],"completed_at":"2025-11-03T10:06:30Z","description":"Tier 1 task (failed): Processing errors","error_summary":{"dependency":2},"errors":[{"affected_count":2,"affected_document_ids":["doc_123","doc_456"],"component":"VertexMultimodalService","error_type":"dependency","message":"Missing required package: google-genai","recovery_suggestion":"Install google-genai package: pip install google-genai","stage":"gemini_extraction","timestamp":"2025-11-03T10:06:00Z"}],"parent_task_id":"task_tier0_abc123","ray_job_id":"raysubmit_XYZ789","source_collection_ids":["col_chunks"],"source_type":"collection","started_at":"2025-11-03T10:05:00Z","status":"FAILED","task_id":"task_tier1_xyz789","tier_num":1}]},"TieringRule":{"properties":{"rule_type":{"type":"string","enum":["auto_evict","auto_archive","auto_rehydrate"],"title":"Rule Type"},"enabled":{"type":"boolean","title":"Enabled","default":false},"threshold_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Threshold Days"}},"type":"object","required":["rule_type"],"title":"TieringRule","description":"A single automatic storage tiering rule (V1: stored but not enforced)."},"TigrisAccessKeyCredentials":{"properties":{"type":{"type":"string","const":"access_key","title":"Type","default":"access_key"},"access_key_id":{"type":"string","minLength":1,"title":"Access Key Id","description":"REQUIRED. Tigris access key ID for authentication. Obtain from: Tigris Console > Access Keys","examples":["tid_AzureDiamond"]},"secret_access_key":{"type":"string","minLength":1,"title":"Secret Access Key","description":"REQUIRED. Tigris secret access key for authentication. SECURITY: This field is encrypted at rest. Never log or expose this value. Obtain from: Tigris Console when creating access key (shown only once)"}},"type":"object","required":["access_key_id","secret_access_key"],"title":"TigrisAccessKeyCredentials","description":"Tigris Data access key credentials.\n\nTigris uses S3-compatible authentication with access keys.\nCredentials can be obtained from the Tigris dashboard at https://console.tigris.dev.\n\nPrerequisites:\n - Create a Tigris account at https://www.tigrisdata.com\n - Create a bucket in the Tigris console\n - Generate access keys from the dashboard\n\nSecurity:\n - secret_access_key is encrypted at rest using MongoDB CSFLE\n - Rotate keys regularly via the Tigris dashboard\n - Use bucket-scoped keys when possible for least privilege\n\nUse Cases:\n - Globally distributed object storage\n - Low-latency content delivery\n - S3-compatible workflows with zero egress fees"},"TigrisConfig":{"properties":{"provider_type":{"type":"string","const":"tigris","title":"Provider Type","default":"tigris"},"credentials":{"$ref":"#/components/schemas/TigrisAccessKeyCredentials","description":"REQUIRED. Tigris access key credentials. Obtain from Tigris Console at https://console.tigris.dev"},"region":{"type":"string","title":"Region","description":"Region for Tigris. Typically 'auto' for automatic global distribution. Tigris automatically distributes data globally, so region is usually 'auto'. Default: auto","default":"auto","examples":["auto"]},"endpoint_url":{"type":"string","title":"Endpoint Url","description":"Tigris S3-compatible endpoint URL. Default: https://fly.storage.tigris.dev This is the standard Tigris endpoint and usually doesn't need to be changed.","default":"https://fly.storage.tigris.dev","examples":["https://fly.storage.tigris.dev"]}},"type":"object","required":["credentials"],"title":"TigrisConfig","description":"Tigris Data globally distributed object storage configuration.\n\nTigris is an S3-compatible object storage service with automatic global\ndistribution, zero egress fees, and built-in CDN capabilities. It uses\nthe AWS S3 API, making integration straightforward.\n\nKey Features:\n - S3-compatible API (drop-in replacement)\n - Automatic global data distribution\n - Zero egress fees\n - Built-in CDN and caching\n - Strong consistency guarantees\n\nAuthentication:\n - Access keys only (similar to S3 access keys)\n - No IAM role assumption (Tigris is not AWS)\n\nRequirements:\n - Tigris account with access keys\n - Bucket created in Tigris console\n - Network connectivity to fly.storage.tigris.dev\n\nUse Cases:\n - Globally distributed media assets\n - Low-latency content delivery worldwide\n - Cost-effective storage with no egress fees\n - S3-compatible workflows outside AWS","examples":[{"credentials":{"access_key_id":"tid_your_access_key","secret_access_key":"tsec_your_secret_key","type":"access_key"},"description":"Standard Tigris configuration","endpoint_url":"https://fly.storage.tigris.dev","provider_type":"tigris","region":"auto"},{"credentials":{"access_key_id":"tid_example_key","secret_access_key":"tsec_example_secret","type":"access_key"},"description":"Tigris with explicit endpoint (default)","provider_type":"tigris"}]},"TikTokConfig":{"properties":{"provider_type":{"type":"string","const":"tiktok","title":"Provider Type","default":"tiktok"},"credentials":{"$ref":"#/components/schemas/TikTokOAuthCredentials","description":"OAuth credentials for TikTok Content API access."},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"OAuth scopes granted during authorization.","default":["user.info.basic","video.list"]}},"type":"object","required":["credentials"],"title":"TikTokConfig","description":"TikTok account configuration via TikTok Content API.\n\nEnables Mixpeek to sync videos from TikTok accounts using the official\nTikTok API. Each video becomes a bucket object with metadata (description,\nlikes, views, shares, comments).\n\nAuthentication:\n - OAuth 2.0 via TikTok Login Kit\n - Access tokens expire in 24h (refresh_token flow)\n\nRequirements:\n - TikTok Developer account with approved app\n - user.info.basic and video.list scopes\n\nUse Cases:\n - Sync creator video content for talent analysis\n - Monitor trending content and competitors\n - Build video content libraries for multimodal search","examples":[{"credentials":{"access_token":"act.xxx","client_key":"your_client_key","client_secret":"your_client_secret","open_id":"user_open_id","refresh_token":"rft.xxx","token_expires_at":"2025-03-02T00:00:00Z","type":"oauth"},"description":"TikTok account via OAuth","provider_type":"tiktok","scopes":["user.info.basic","video.list"]}]},"TikTokOAuthCredentials":{"properties":{"type":{"type":"string","const":"oauth","title":"Type","default":"oauth"},"client_key":{"type":"string","title":"Client Key","description":"TikTok App Client Key from Developer Portal."},"client_secret":{"type":"string","title":"Client Secret","description":"SECURITY: Encrypted at rest via CSFLE. TikTok App Client Secret from Developer Portal."},"access_token":{"type":"string","title":"Access Token","description":"SECURITY: Encrypted at rest. TikTok access token (24h validity)."},"refresh_token":{"type":"string","title":"Refresh Token","description":"SECURITY: Encrypted at rest. Used to obtain new access tokens."},"token_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Token Expires At","description":"Access token expiration timestamp."},"open_id":{"type":"string","title":"Open Id","description":"TikTok user's open_id from the authorization response."}},"type":"object","required":["client_key","client_secret","access_token","refresh_token","open_id"],"title":"TikTokOAuthCredentials","description":"Credentials for TikTok Content API OAuth2 authentication.\n\nTikTok uses OAuth2 via TikTok Login Kit. Access tokens are short-lived\n(24 hours) and must be refreshed using the refresh token.\n\nPrerequisites:\n - TikTok Developer account with an approved app\n - App must have user.info.basic and video.list scopes\n\nSecurity:\n - client_secret, access_token, and refresh_token encrypted at rest via CSFLE\n - Access tokens expire in 24h; refresh tokens used for renewal\n - Token refresh happens automatically during sync execution"},"TimeRange-Input":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start","description":"Start of time range (inclusive)."},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End","description":"End of time range (inclusive)."}},"type":"object","title":"TimeRange","description":"Time range filter for session queries."},"TokenizerType":{"type":"string","enum":["word","whitespace","prefix","multilingual"],"title":"TokenizerType","description":"Tokenizer type."},"ToolInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Tool name"},"description":{"type":"string","title":"Description","description":"Tool description"},"category":{"type":"string","title":"Category","description":"Tool category"},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Parameter definitions"},"required_params":{"items":{"type":"string"},"type":"array","title":"Required Params","description":"Required parameters"},"requires_confirmation":{"type":"boolean","title":"Requires Confirmation","description":"Whether the tool requires user confirmation","default":false}},"type":"object","required":["name","description","category"],"title":"ToolInfo","description":"Information about an available agent tool.\n\nAttributes:\n name: Tool name (use this in available_tools)\n description: What the tool does\n category: Tool category (search, read, create, etc.)\n parameters: Parameter definitions\n required_params: List of required parameter names\n requires_confirmation: Whether the tool requires user confirmation before execution"},"TransitionLifecycleRequest":{"properties":{"lifecycle_state":{"$ref":"#/components/schemas/LifecycleState","description":"Target lifecycle state for the collection"},"async_transition":{"type":"boolean","title":"Async Transition","description":"If False, block until the transition completes","default":true}},"type":"object","required":["lifecycle_state"],"title":"TransitionLifecycleRequest"},"TransitionPath":{"properties":{"path":{"items":{"type":"string"},"type":"array","minItems":2,"title":"Path","description":"Ordered sequence of steps","examples":[["inquiry","followup","closed_won"],["draft","review","published"]]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Number of sequences following this path"},"percentage":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Percentage","description":"Percentage of total completing sequences"},"avg_duration_sec":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Sec","description":"Average time to complete this path (seconds)"}},"type":"object","required":["path","count","percentage"],"title":"TransitionPath","description":"Represents a multi-step path between two steps.\n\nTracks the intermediate steps documents take when transitioning from\nfrom_step to to_step.\n\nAttributes:\n path: Ordered sequence of steps (e.g., [\"inquiry\", \"followup\", \"proposal\", \"closed_won\"])\n count: Number of sequences that followed this exact path\n percentage: Percentage of all completing sequences that used this path\n avg_duration_sec: Average time to complete this path\n\nExample:\n ```python\n # 30% of successful conversions took this 4-step path\n TransitionPath(\n path=[\"inquiry\", \"followup\", \"proposal\", \"closed_won\"],\n count=120,\n percentage=34.3,\n avg_duration_sec=604800.0 # 7 days average\n )\n ```"},"TriggerActionType":{"type":"string","enum":["cluster","taxonomy_enrichment","batch_rerun","collection_trigger"],"title":"TriggerActionType","description":"Type of action to execute when trigger fires.\n\nSupported action types:\n- **cluster**: Execute clustering on a cluster definition\n- **taxonomy_enrichment**: Apply taxonomy enrichment to a collection\n- **batch_rerun**: Re-execute a completed/failed batch"},"TriggerCollectionRequest":{"properties":{"include_buckets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include Buckets","description":"Limit processing to objects from these specific buckets (IDs or names). Only applies to bucket-sourced collections. If not provided, all configured source buckets are used."},"include_collections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include Collections","description":"Limit processing to documents from these specific collections (IDs or names). Only applies to collection-sourced collections. If not provided, all configured source collections are used."},"source_filters":{"anyOf":[{"$ref":"#/components/schemas/LogicalOperator-Input"},{"type":"null"}],"description":"Field-level filters for objects (bucket-sourced) or documents (collection-sourced). Uses LogicalOperator format (AND/OR/NOT). Use this to filter by metadata fields, status, or any other object/document properties.","examples":[{"AND":[{"field":"status","operator":"eq","value":"pending"}]},{"AND":[{"field":"object_id","operator":"in","value":["obj_1","obj_2"]}]}]}},"type":"object","title":"TriggerCollectionRequest","description":"Request to trigger (re)processing through a collection.\n\n**For bucket-sourced collections (tier 0):**\nDiscovers objects from source bucket(s) and creates a batch for processing.\nUse `include_buckets` to limit which source buckets to process from.\n\n**For collection-sourced collections (tier N):**\nProcesses existing documents from upstream collection(s).\nUse `include_collections` to limit which source collections to process from.\n\nUse `source_filters` for field-level filtering on objects or documents.\n\n**Document Overwrite Behavior:**\n- If source bucket has `unique_key` configured: Documents are UPSERTED (overwrites existing)\n- If source bucket has NO `unique_key`: New documents are CREATED (may cause duplicates)\n\nTo enable idempotent re-processing, configure `unique_key` on the source bucket."},"TriggerCollectionResponse":{"properties":{"batch_id":{"type":"string","title":"Batch Id","description":"ID of the created batch for tracking progress."},"task_id":{"type":"string","title":"Task Id","description":"Task ID for monitoring via GET /v1/tasks/{task_id}."},"collection_id":{"type":"string","title":"Collection Id","description":"ID of the collection being processed."},"source_bucket_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Source Bucket Ids","description":"Bucket IDs that objects were discovered from (bucket-sourced collections)."},"source_collection_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Source Collection Ids","description":"Collection IDs that documents were read from (collection-sourced collections)."},"object_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Object Count","description":"Total number of objects included in the batch (bucket-sourced collections)."},"document_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Document Count","description":"Total number of documents to process (collection-sourced collections)."},"total_tiers":{"type":"integer","title":"Total Tiers","description":"Number of processing tiers in the DAG."},"message":{"type":"string","title":"Message","description":"Human-readable status message."}},"type":"object","required":["batch_id","task_id","collection_id","total_tiers","message"],"title":"TriggerCollectionResponse","description":"Response after triggering collection processing.\n\nUse `batch_id` or `task_id` to monitor progress via GET /v1/batches/{batch_id}\nor GET /v1/tasks/{task_id}."},"TriggerExecutionConfig":{"properties":{"collection_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Collection Ids","description":"REQUIRED. List of collection IDs to cluster when trigger fires. Must contain at least one collection ID. All collections will be clustered together using the specified algorithm.","examples":[["col_abc123"],["col_products","col_inventory"]]},"config":{"additionalProperties":true,"type":"object","title":"Config","description":"REQUIRED. Clustering algorithm configuration. Must include 'algorithm' field ('kmeans', 'hdbscan', 'hierarchical'). Additional fields depend on algorithm choice. K-means requires 'n_clusters'. HDBSCAN requires 'min_cluster_size'.","examples":[{"algorithm":"kmeans","min_cluster_size":2,"n_clusters":5},{"algorithm":"hdbscan","min_cluster_size":10}]}},"type":"object","required":["collection_ids","config"],"title":"TriggerExecutionConfig","description":"Configuration for cluster execution when trigger fires.\n\nDefines what clustering algorithm and parameters to use when the trigger executes.\n\nExamples:\n K-means clustering on 3 collections:\n {\n \"collection_ids\": [\"col_abc123\", \"col_def456\", \"col_ghi789\"],\n \"config\": {\n \"algorithm\": \"kmeans\",\n \"n_clusters\": 5,\n \"min_cluster_size\": 2\n }\n }\n\n HDBSCAN clustering on single collection:\n {\n \"collection_ids\": [\"col_products\"],\n \"config\": {\n \"algorithm\": \"hdbscan\",\n \"min_cluster_size\": 10,\n \"min_samples\": 5\n }\n }"},"TriggerExecutionHistory":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Task ID"},"triggered_at":{"type":"string","format":"date-time","title":"Triggered At","description":"When trigger fired"},"status":{"type":"string","title":"Status","description":"Execution status"},"execution_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Execution Time Ms","description":"Execution time in milliseconds"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"}},"type":"object","required":["task_id","triggered_at","status"],"title":"TriggerExecutionHistory","description":"Single execution history item."},"TriggerExecutionHistoryItem":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job ID"},"triggered_at":{"type":"string","format":"date-time","title":"Triggered At","description":"When trigger fired"},"status":{"type":"string","title":"Status","description":"Execution status"},"execution_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Execution Time Ms","description":"Execution time in milliseconds"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if failed"},"num_clusters":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Num Clusters","description":"Number of clusters created"},"num_documents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Num Documents","description":"Number of documents processed"}},"type":"object","required":["job_id","triggered_at","status"],"title":"TriggerExecutionHistoryItem","description":"Single execution history item."},"TriggerHistoryRequest":{"properties":{"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Pagination offset","default":0},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Results per page","default":50},"status_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter","description":"Filter by execution status"}},"type":"object","title":"TriggerHistoryRequest","description":"Request for trigger execution history."},"TriggerTierRequest":{"properties":{"internal_id":{"type":"string","title":"Internal Id"},"namespace_id":{"type":"string","title":"Namespace Id"},"ray_job_id":{"type":"string","title":"Ray Job Id"},"completed_tier":{"type":"integer","title":"Completed Tier"},"start_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Start Time Ms"},"end_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"End Time Ms"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["internal_id","namespace_id","ray_job_id","completed_tier"],"title":"TriggerTierRequest","description":"Request to trigger next tier processing."},"UnifiedExtractorListResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the request succeeded","default":true},"extractors":{"items":{"$ref":"#/components/schemas/UnifiedExtractorResponse"},"type":"array","title":"Extractors","description":"List of all available extractors"},"total":{"type":"integer","title":"Total","description":"Total number of extractors"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"builtin_count":{"type":"integer","title":"Builtin Count","description":"Number of builtin extractors"},"custom_count":{"type":"integer","title":"Custom Count","description":"Number of custom extractors (org + namespace level)"}},"type":"object","required":["extractors","total","namespace_id","builtin_count","custom_count"],"title":"UnifiedExtractorListResponse","description":"Response for listing all extractors available to a namespace."},"UnifiedExtractorResponse":{"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"},"feature_extractor_id":{"type":"string","title":"Feature Extractor Id","description":"Unique identifier (name_version)"},"source":{"$ref":"#/components/schemas/ExtractorSource","description":"Origin of this extractor: 'builtin' (shipped with Mixpeek), 'custom' (user-uploaded plugin), or 'community' (marketplace)"},"description":{"type":"string","title":"Description","description":"Human-readable description"},"icon":{"type":"string","title":"Icon","description":"Lucide-react icon name for frontend rendering","default":"box"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON schema for input data"},"output_schema":{"additionalProperties":true,"type":"object","title":"Output Schema","description":"JSON schema for output data"},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema","description":"JSON schema for parameters"},"supported_input_types":{"items":{"type":"string"},"type":"array","title":"Supported Input Types","description":"Supported input types (video, image, text, etc.)"},"max_inputs":{"additionalProperties":{"type":"integer"},"type":"object","title":"Max Inputs","description":"Maximum number of inputs per type"},"default_parameters":{"additionalProperties":true,"type":"object","title":"Default Parameters","description":"Default parameter values"},"costs":{"anyOf":[{"$ref":"#/components/schemas/CostsInfo"},{"type":"null"}],"description":"Credit cost information (builtin extractors only)"},"required_vector_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/VectorIndexDefinition"},"type":"array"},{"type":"null"}],"title":"Required Vector Indexes","description":"Vector indexes this extractor produces"},"required_payload_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayloadIndexConfig-Output"},"type":"array"},{"type":"null"}],"title":"Required Payload Indexes","description":"Payload indexes required by this extractor"},"position_fields":{"items":{"type":"string"},"type":"array","title":"Position Fields","description":"Fields that identify unique positions within output documents. Used for deterministic document ID generation."},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Primary feature URI (e.g., mixpeek://text_extractor@v1/embedding)"},"plugin_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plugin Id","description":"Plugin ID (custom plugins only)"},"deployed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deployed","description":"Whether the plugin is deployed (custom plugins only)"},"validation_status":{"anyOf":[{"type":"string","enum":["pending","passed","failed"]},{"type":"null"}],"title":"Validation Status","description":"Validation status (custom plugins only)"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Creation timestamp (custom plugins only)"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"Last update timestamp (custom plugins only)"}},"type":"object","required":["feature_extractor_name","version","feature_extractor_id","source","description","input_schema","output_schema"],"title":"UnifiedExtractorResponse","description":"Unified extractor response combining builtin and custom plugins.\n\nThis model provides a consistent view of all extractors available\nto a namespace, regardless of whether they are builtin or custom."},"UniqueKeyConfig":{"properties":{"fields":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Fields","description":"Field name(s) from bucket schema to use as unique constraint. REQUIRED - must provide at least one field name. \n\nSingle field example: ['video_id'] - Enforces uniqueness on video_id alone. Compound example: ['sensor_id', 'timestamp'] - Uniqueness requires BOTH fields to match. \n\nAll specified fields must:\n - Exist in the bucket schema\n - Be scalar types (string, integer, float, uuid - NOT objects or arrays)\n - Have non-null, non-empty values in all uploaded objects\n - Be 255 characters or less per string field value\n\n\nField order doesn't matter (sorted internally for consistency). ['timestamp', 'sensor_id'] is equivalent to ['sensor_id', 'timestamp'].","examples":[["video_id"],["product_sku"],["user_id","session_id"],["sensor_id","timestamp"],["product_id","size","color"]]},"default_policy":{"anyOf":[{"type":"string","enum":["insert","update","upsert"]},{"type":"null"}],"title":"Default Policy","description":"Default insertion policy for this bucket when not specified per request. OPTIONAL - if omitted, you must provide ?policy= parameter on each upload request.\n\nPolicies:\n - 'insert': Create new object only. Fail with 409 Conflict if unique key already exists.\n Use when: You want to prevent accidental overwrites (safest option).\n\n - 'update': Update existing object only. Fail with 404 Not Found if unique key doesn't exist.\n Use when: You only want to update existing records, never create new ones.\n\n - 'upsert': Update if exists, create if not (idempotent operation).\n Use when: You want idempotent ingestion (re-running is safe).\n\nPolicy Resolution:\n 1. Request-level ?policy= parameter takes precedence (if provided)\n 2. Falls back to this default_policy (if configured)\n 3. Returns 400 Bad Request if neither is specified\n\nRecommendation: Omit default_policy if you want explicit control on each upload. Set default_policy='upsert' for idempotent pipelines.","examples":["insert","update","upsert"]}},"type":"object","required":["fields"],"title":"UniqueKeyConfig","description":"Configuration for bucket unique key enforcement.\n\nEnables automatic uniqueness enforcement on one or more fields from the bucket schema.\nSupports both single field and compound (multi-field) uniqueness constraints.\n\nWhen configured, the bucket will maintain a lookup table mapping unique key values\nto document IDs, enabling efficient upsert operations and preventing duplicates.\n\n**Impact on Collection Trigger/Re-processing:**\nWhen a collection is triggered (POST /collections/{id}/trigger), the unique_key\ndetermines whether documents are overwritten or duplicated:\n- WITH unique_key: Documents get deterministic IDs ā†’ re-triggering OVERWRITES existing docs\n- WITHOUT unique_key: Documents get random IDs ā†’ re-triggering CREATES DUPLICATES\n\nFor idempotent pipelines where re-triggering is safe, configure a unique_key.\n\n**Relationship to Extractor position_fields:**\nThe `unique_key` (bucket-level) and `position_fields` (extractor-level) work together\nto generate deterministic document IDs:\n\n- `unique_key`: Identifies unique SOURCE OBJECTS in the bucket (e.g., video_id)\n- `position_fields`: Identifies unique OUTPUT DOCUMENTS from a single object (e.g., start_time, end_time)\n\nDocument ID Formula:\n document_id = hash(source_object_key + extractor_id + collection_id + position_field_values)\n\nExample - Processing a 60-second video with 10-second segments:\n - Bucket unique_key: [\"video_id\"] ā†’ Identifies the source video\n - Extractor position_fields: [\"start_time\", \"end_time\"] ā†’ Identifies each segment\n - Result: 6 unique document IDs (one per segment), all deterministic\n\nWithout position_fields, all segments would get the SAME document_id and overwrite each other.\nWithout unique_key, reprocessing would create DUPLICATE documents instead of updating.\n\nRequirements:\n - fields: REQUIRED - Array of field names from bucket schema to use as unique constraint\n - default_policy: OPTIONAL - Bucket-level default insertion policy (can be overridden per request)\n - All specified fields must exist in the bucket schema\n - All fields must be scalar types (string, integer, float, uuid)\n - Field values cannot be null or empty in uploaded objects\n - Cannot be changed after bucket creation (v1 limitation)\n\nUse Cases:\n - Single field uniqueness: [\"video_id\"], [\"product_sku\"], [\"user_email\"]\n - Compound uniqueness: [\"sensor_id\", \"timestamp\"], [\"product_id\", \"size\", \"color\"]\n - With default policy: Enables idempotent ingestion without per-request policy\n - Without default: Requires explicit policy on each upload (safer, more intentional)\n\nInsertion Policies:\n - 'insert': Fail with 409 Conflict if key exists (prevents accidental overwrites)\n - 'update': Fail with 404 Not Found if key doesn't exist (updates only)\n - 'upsert': Update if exists, insert if not (idempotent ingestion)\n\nPolicy Resolution (when uploading objects):\n 1. Use request-level ?policy= parameter if provided (highest priority)\n 2. Fall back to bucket-level default_policy if configured\n 3. Return 400 Bad Request if neither is specified (prevents accidental operations)\n\nExamples:\n Single field with upsert default (idempotent video ingestion):\n {\n \"fields\": [\"video_id\"],\n \"default_policy\": \"upsert\"\n }\n\n Single field with insert default (prevent duplicate products):\n {\n \"fields\": [\"product_sku\"],\n \"default_policy\": \"insert\"\n }\n\n Compound fields with upsert (time-series sensor data):\n {\n \"fields\": [\"sensor_id\", \"timestamp\"],\n \"default_policy\": \"upsert\"\n }\n\n Compound fields without default (explicit policy required):\n {\n \"fields\": [\"user_id\", \"session_id\"]\n }","examples":[{"default_policy":"upsert","description":"Single field, upsert by default (idempotent video ingestion)","fields":["video_id"]},{"default_policy":"insert","description":"Single field, insert by default (prevent duplicate products)","fields":["product_sku"]},{"description":"Single field, no default policy (explicit required per upload)","fields":["user_id"]},{"default_policy":"insert","description":"Compound fields, insert by default (time-series with duplicate prevention)","fields":["sensor_id","timestamp"]},{"default_policy":"upsert","description":"Compound fields, upsert by default (product variants, idempotent)","fields":["product_id","size","color"]},{"description":"Compound fields, no default (explicit policy required)","fields":["user_id","session_id"]},{"default_policy":"update","description":"Three-field compound key, update only (profile updates)","fields":["tenant_id","user_id","profile_version"]}]},"UpdateNamespaceRequest":{"properties":{"namespace_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Namespace Name","description":"Name of the namespace to update","example":"spotify_playlists_dev"},"payload_indexes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayloadIndexConfig-Input"},"type":"array"},{"type":"null"}],"title":"Payload Indexes","description":"Updated list of payload index configurations","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":false,"type":"keyword"},"is_protected":false,"type":"keyword"}]}},"type":"object","title":"UpdateNamespaceRequest","description":"Request schema for updating a namespace's payload indexes."},"UpdateObjectRequest":{"properties":{"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Prefix","description":"Updated 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."},"blobs":{"anyOf":[{"items":{"$ref":"#/components/schemas/CreateBlobRequest"},"type":"array"},{"type":"null"}],"title":"Blobs","description":"List of new or updated blobs for this object"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Updated metadata for the object, this will be merged with existing metadata."},"skip_duplicates":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Duplicates","description":"Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped."}},"type":"object","title":"UpdateObjectRequest","description":"Request model for updating an existing bucket object."},"UpdatePageRequest":{"properties":{"slug":{"anyOf":[{"type":"string","maxLength":60,"minLength":3,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},{"type":"null"}],"title":"Slug"},"template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template"},"sections":{"anyOf":[{"items":{"$ref":"#/components/schemas/SectionConfig"},"type":"array"},{"type":"null"}],"title":"Sections"},"custom_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Html"},"meta":{"anyOf":[{"$ref":"#/components/schemas/PageMeta"},{"type":"null"}]},"hero":{"anyOf":[{"$ref":"#/components/schemas/HeroConfig"},{"type":"null"}]},"theme":{"anyOf":[{"$ref":"#/components/schemas/ThemeConfig"},{"type":"null"}]},"seo":{"anyOf":[{"$ref":"#/components/schemas/SEOConfig"},{"type":"null"}]},"stats":{"anyOf":[{"items":{"$ref":"#/components/schemas/StatItem"},"type":"array"},{"type":"null"}],"title":"Stats"},"featured_gallery":{"anyOf":[{"$ref":"#/components/schemas/FeaturedGalleryConfig-Input"},{"type":"null"}]},"tabs":{"anyOf":[{"items":{"$ref":"#/components/schemas/PageTab-Input"},"type":"array"},{"type":"null"}],"title":"Tabs"},"password_secret_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password Secret Name"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"UpdatePageRequest","description":"Request to update an existing Page (all fields optional)."},"UpdatePreferencesRequest":{"properties":{"preferences":{"additionalProperties":true,"type":"object","title":"Preferences","description":"Updated notification preferences"}},"type":"object","required":["preferences"],"title":"UpdatePreferencesRequest","description":"Request model for updating notification preferences."},"UpdatePublishedRetrieverRequest":{"properties":{"display_config":{"anyOf":[{"$ref":"#/components/schemas/DisplayConfig-Input"},{"type":"null"}],"description":"Update the display configuration"},"rate_limit_config":{"anyOf":[{"$ref":"#/components/schemas/RateLimitConfig"},{"type":"null"}],"description":"Update rate limiting configuration"},"password_secret_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password Secret Name","description":"Update or remove password protection (set to empty string to remove)"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Activate or deactivate the published retriever"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Update tags for categorizing this retriever"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Update the primary category for this retriever"}},"type":"object","title":"UpdatePublishedRetrieverRequest","description":"Request to update a published retriever configuration."},"UpdateReminderPreferencesRequest":{"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Master toggle for all reminders"},"onboarding_nudges":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Onboarding Nudges","description":"Enable/disable onboarding nudges"},"engagement_reminders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Engagement Reminders","description":"Enable/disable engagement reminders"},"feature_tips":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Feature Tips","description":"Enable/disable feature tips"},"quiet_hours_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quiet Hours Start","description":"Hour (0-23) to start quiet period (UTC)"},"quiet_hours_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quiet Hours End","description":"Hour (0-23) to end quiet period (UTC)"}},"type":"object","title":"UpdateReminderPreferencesRequest","description":"Request model for updating reminder preferences."},"UpdateSecretRequest":{"properties":{"secret_value":{"type":"string","minLength":1,"title":"Secret Value","description":"REQUIRED. New plaintext value for the secret. This will replace the existing encrypted value. The old value is permanently overwritten with no history. The new value will be encrypted at rest using Fernet encryption. Use this to rotate keys, update expired tokens, or change credentials. Format: any string (will be encrypted as-is).","examples":["YOUR_STRIPE_API_KEY","ghp_rotated_token_def456","new_api_key_ghi789"]}},"type":"object","required":["secret_value"],"title":"UpdateSecretRequest","description":"Request to update an existing secret in the organization vault.\n\nUpdates the encrypted value of an existing secret. The old value is\npermanently overwritten with no history or rollback capability.\n\n**Use Cases**:\n- Rotate API keys periodically for security\n- Update expired tokens\n- Change credentials after security incident\n- Switch from test to production keys\n\n**Security**:\n- Old value is permanently overwritten (no history)\n- New value is encrypted before storage\n- No rollback or undo capability\n- Update is logged for audit trail\n\n**Requirements**:\n- secret_value: REQUIRED, new plaintext value\n- Secret must already exist (use POST to create)\n\n**Permissions**: Requires ADMIN permission to update secrets.","examples":[{"description":"Rotate Stripe API key","secret_value":"YOUR_STRIPE_API_KEY"},{"description":"Update expired GitHub token","secret_value":"ghp_new_token_def456"},{"description":"Switch from test to production key","secret_value":"YOUR_STRIPE_API_KEY"}]},"UpdateSpendingCapsRequest":{"properties":{"monthly_spending_budget":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Monthly Spending Budget","description":"Soft spending limit in USD cents. Triggers alerts but doesn't block API access. Set to null to remove budget limit.","examples":[10000,50000,100000]},"spending_alert_thresholds":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Spending Alert Thresholds","description":"Percentage thresholds for spending alerts (0-100). When current spending reaches each threshold, an alert is sent.","examples":[[50,75,90,100],[80,100]]},"spending_alerts_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Spending Alerts Enabled","description":"Whether to send spending alerts when thresholds are crossed."},"hard_spending_cap":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Hard Spending Cap","description":"Hard spending limit in USD cents. When reached, API access is blocked. Set to null to remove hard cap.","examples":[50000,100000,500000]},"hard_cap_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hard Cap Enabled","description":"Whether to enforce the hard spending cap."}},"type":"object","title":"UpdateSpendingCapsRequest","description":"Request to update spending cap configuration."},"UploadListStats":{"properties":{"total_uploads":{"type":"integer","title":"Total Uploads","description":"Total number of uploads in the result set"},"total_size_bytes":{"type":"integer","title":"Total Size Bytes","description":"Total size of all files in bytes"},"uploads_by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"Uploads By Status","description":"Count of uploads grouped by status","examples":[{"COMPLETED":35,"FAILED":2,"PENDING":5}]},"avg_file_size_bytes":{"type":"number","title":"Avg File Size Bytes","description":"Average file size across all uploads"},"unique_buckets":{"type":"integer","title":"Unique Buckets","description":"Number of unique buckets in the result set"}},"type":"object","required":["total_uploads","total_size_bytes","uploads_by_status","avg_file_size_bytes","unique_buckets"],"title":"UploadListStats","description":"Aggregate statistics for a list of uploads."},"UploadPerformanceMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket","description":"Time bucket timestamp"},"upload_count":{"type":"integer","title":"Upload Count","description":"Number of uploads"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average upload latency"},"p95_latency_ms":{"type":"number","title":"P95 Latency Ms","description":"95th percentile latency"},"p99_latency_ms":{"type":"number","title":"P99 Latency Ms","description":"99th percentile latency"},"avg_throughput_mbps":{"type":"number","title":"Avg Throughput Mbps","description":"Average throughput in MB/s"},"error_rate":{"type":"number","title":"Error Rate","description":"Error rate (0-1)"}},"type":"object","required":["time_bucket","upload_count","avg_latency_ms","p95_latency_ms","p99_latency_ms","avg_throughput_mbps","error_rate"],"title":"UploadPerformanceMetric","description":"Upload performance metrics for a time bucket."},"UploadPerformanceResponse":{"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/UploadPerformanceMetric"},"type":"array","title":"Metrics","description":"Upload performance metrics"},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Summary statistics"}},"type":"object","required":["bucket_id","time_range","metrics"],"title":"UploadPerformanceResponse","description":"Upload performance analytics response."},"UploadResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id","description":"Unique identifier for this upload. Auto-generated. \n\nāš ļø NEXT STEP: After uploading to S3, you MUST confirm: POST /v1/uploads/{upload_id}/confirm \n\nOther operations: - Check status: GET /v1/uploads/{upload_id} - Cancel upload: DELETE /v1/uploads/{upload_id} \n\nFormat: 'upl_' followed by 16 random characters.","examples":["upl_a1b2c3d4e5f6","upl_x9y8z7w6v5u4"]},"bucket_id":{"type":"string","title":"Bucket Id","description":"Target bucket ID where object will be created","examples":["bkt_abc123"]},"filename":{"type":"string","title":"Filename","description":"Name of the file to upload","examples":["product_video.mp4"]},"content_type":{"type":"string","title":"Content Type","description":"MIME type enforced by the presigned URL","examples":["video/mp4"]},"file_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size Bytes","description":"Expected file size in bytes if provided in request. Will be validated during confirmation.","examples":[10485760]},"presigned_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Presigned Url","description":"Time-limited HTTPS URL for uploading directly to S3. \n\n**Step 1 - Upload to S3:** curl -X PUT '{presigned_url}' -H 'Content-Type: {content_type}' --upload-file {filename} \n\n**Step 2 - REQUIRED: Confirm the upload:** POST /v1/uploads/{upload_id}/confirm (S3 has no callback - you MUST call confirm to finalize) \n\nThe URL includes authentication and expires after presigned_url_expiration seconds. S3 returns an ETag header on success - pass it to confirm for integrity validation. NOTE: This will be null if is_duplicate=true (duplicate found, no upload needed)."},"presigned_url_expiration":{"type":"integer","title":"Presigned Url Expiration","description":"How long the presigned URL is valid, in seconds","examples":[3600]},"s3_key":{"type":"string","title":"S3 Key","description":"Full S3 object key where the file will be stored. Format: {internal_id}/{namespace_id}/api_buckets_uploads_create/{upload_id}/{filename}. Used internally for verification and object creation.","examples":["int_xyz/ns_abc/api_buckets_uploads_create/upl_123/video.mp4"]},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"Current upload status. After creation, always PENDING. Possible statuses: PENDING ā†’ IN_PROGRESS ā†’ PROCESSING ā†’ COMPLETED/FAILED/CANCELED","examples":["PENDING"]},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Custom metadata for tracking"},"create_object_on_confirm":{"type":"boolean","title":"Create Object On Confirm","description":"Whether bucket object will be auto-created on confirmation"},"object_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Object Metadata","description":"Metadata for the bucket object (if create_object_on_confirm=true)"},"blob_property":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blob Property","description":"Property name for the blob in bucket object"},"blob_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blob Type","description":"Type of blob (IMAGE, VIDEO, etc.)"},"file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Hash","description":"SHA256 hash of the file content. Set during confirmation from S3 metadata or provided in request. Used for duplicate detection.","examples":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]},"skip_duplicates":{"type":"boolean","title":"Skip Duplicates","description":"Whether duplicate detection was enabled for this upload","default":true},"is_duplicate":{"type":"boolean","title":"Is Duplicate","description":"Whether this upload was identified as a duplicate of an existing file. If true: - duplicate_of_upload_id contains the original upload - presigned_url will be null (no upload needed) - You can use the original upload's S3 object. This saves bandwidth and storage costs.","default":false},"duplicate_of_upload_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate Of Upload Id","description":"If skip_duplicates=true and duplicate found, this is the original upload_id. The response will reference the existing upload instead of creating a new one.","examples":["upl_original123"]},"skipped_unique_key":{"type":"boolean","title":"Skipped Unique Key","description":"Whether this upload was skipped because the unique key already exists in the bucket. If true: - existing_object_id contains the ID of the existing object - presigned_url will be null (no upload needed) - No S3 upload is required This saves bandwidth and prevents duplicate objects.","default":false},"existing_object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Existing Object Id","description":"If skipped_unique_key=true, this is the object_id of the existing object that has the same unique key values. The upload was skipped to prevent duplicates.","examples":["obj_abc123xyz789"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable message about the upload. Provided when is_duplicate=true or other special conditions. Example: 'File already exists with the same content hash. No upload needed - returning existing upload.'"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this upload record was created (ISO 8601 format)","examples":["2024-01-15T10:30:00Z"]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the presigned URL expires (ISO 8601 format). After this time: - The presigned URL cannot be used - Upload status will be marked as FAILED if not completed - The upload record will be auto-deleted 30 days later (MongoDB TTL)","examples":["2024-01-15T11:30:00Z"]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the upload was completed and verified (ISO 8601 format)","examples":["2024-01-15T10:35:00Z"]},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At","description":"When S3 object existence was verified (ISO 8601 format)","examples":["2024-01-15T10:35:00Z"]},"etag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Etag","description":"S3 ETag from the uploaded object (set during confirmation)","examples":["d41d8cd98f00b204e9800998ecf8427e"]},"object_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Object Id","description":"Created bucket object ID (if create_object_on_confirm was true)","examples":["obj_a1b2c3d4e5f6"]},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Celery task ID for async confirmation (if processed asynchronously)","examples":["task_abc123"]}},"type":"object","required":["upload_id","bucket_id","filename","content_type","presigned_url_expiration","s3_key","status","create_object_on_confirm","created_at","expires_at"],"title":"UploadResponse","description":"Response containing presigned URL and upload tracking information.\n\nThis response includes everything needed to:\n1. Upload your file to S3 using the presigned_url\n2. Track the upload status using upload_id\n3. Confirm the upload using the confirmation endpoint\n\nThe presigned_url is time-limited and specific to this upload.\nAfter uploading to S3, call POST /v1/buckets/{bucket_id}/uploads/{upload_id}/confirm.","examples":[{"blob_property":"video","blob_type":"VIDEO","bucket_id":"bkt_prod_videos","content_type":"video/mp4","create_object_on_confirm":true,"created_at":"2024-01-15T10:30:00Z","description":"New upload ready for S3 - object will be created on confirm (DEFAULT)","expires_at":"2024-01-15T11:30:00Z","file_size_bytes":52428800,"filename":"product_demo.mp4","is_duplicate":false,"object_metadata":{"category":"tutorials"},"presigned_url":"https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...","presigned_url_expiration":3600,"s3_key":"int_xyz/ns_abc/api_buckets_uploads_create/upl_abc123xyz789/product_demo.mp4","skip_duplicates":true,"status":"PENDING","upload_id":"upl_abc123xyz789"},{"bucket_id":"bkt_prod_videos","completed_at":"2024-01-10T08:25:00Z","content_type":"video/mp4","created_at":"2024-01-10T08:20:00Z","description":"Duplicate detected - no upload needed, existing object returned","duplicate_of_upload_id":"upl_original456","file_hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","file_size_bytes":52428800,"filename":"product_demo.mp4","is_duplicate":true,"message":"File already exists with the same content hash. No upload needed - returning existing upload.","object_id":"obj_existing789","s3_key":"int_xyz/ns_abc/api_buckets_uploads_create/upl_original456/product_demo.mp4","status":"COMPLETED","upload_id":"upl_original456"},{"bucket_id":"bkt_media","content_type":"video/mp4","create_object_on_confirm":false,"created_at":"2024-01-15T10:30:00Z","description":"ADVANCED: Manual object creation (create_object_on_confirm=false)","expires_at":"2024-01-15T11:30:00Z","filename":"video.mp4","note":"Only use when combining multiple uploads into one object","presigned_url":"https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...","presigned_url_expiration":3600,"s3_key":"int_xyz/ns_abc/api_buckets_uploads_create/upl_manual789/video.mp4","status":"PENDING","upload_id":"upl_manual789","workflow":["1. User uploads file to presigned_url","2. POST /uploads/upl_manual789/confirm (verifies upload, no object created)","3. POST /buckets/{id}/objects with upload_id reference:"," {blobs: [{property: 'video', upload_id: 'upl_manual789'}]}"]}]},"UsageBreakdownResponse":{"properties":{"billing_month":{"type":"string","title":"Billing Month","description":"Billing month (YYYY-MM)","examples":["2025-12"]},"total_credits":{"type":"integer","title":"Total Credits","description":"Total credits consumed","examples":[23450]},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Total cost in USD","examples":[23.45]},"by_operation":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Operation","description":"Credits consumed by operation type","examples":[{"batch":2450,"extractor":15000,"search":1000,"upload":5000}]},"by_extractor":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Extractor","description":"Credits consumed by extractor","examples":[{"multimodal_extractor":10000,"text_extractor":5000}]},"period_start":{"type":"string","format":"date-time","title":"Period Start","description":"Start of billing period"},"period_end":{"type":"string","format":"date-time","title":"Period End","description":"End of billing period"}},"type":"object","required":["billing_month","total_credits","total_cost_usd","by_operation","by_extractor","period_start","period_end"],"title":"UsageBreakdownResponse","description":"Response with detailed usage breakdown."},"UsageMetric":{"properties":{"time_bucket":{"type":"string","format":"date-time","title":"Time Bucket","description":"Time bucket timestamp"},"storage_gb_hours":{"type":"number","title":"Storage Gb Hours","description":"Storage GB-hours"},"upload_operations":{"type":"integer","title":"Upload Operations","description":"Upload operation count"},"sync_operations":{"type":"integer","title":"Sync Operations","description":"Sync operation count"},"total_credits":{"type":"integer","title":"Total Credits","description":"Total credits consumed"},"estimated_cost_usd":{"type":"number","title":"Estimated Cost Usd","description":"Estimated cost in USD"}},"type":"object","required":["time_bucket","storage_gb_hours","upload_operations","sync_operations","total_credits","estimated_cost_usd"],"title":"UsageMetric","description":"Usage and cost metrics for a time bucket."},"UsageStatistics":{"properties":{"total_queries":{"type":"integer","title":"Total Queries","description":"Total number of queries executed","default":0},"queries_last_24h":{"type":"integer","title":"Queries Last 24H","description":"Number of queries in the last 24 hours","default":0},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms","description":"Average latency in milliseconds","default":0.0},"error_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Error Rate","description":"Error rate as a fraction (0.0 - 1.0)","default":0.0},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Most recent error message for debugging"},"cache_hit_rate":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Cache Hit Rate","description":"Cache hit rate if caching is enabled (0.0 - 1.0)"}},"type":"object","title":"UsageStatistics","description":"Usage statistics for a retriever."},"UserCreateRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Unique email address within the organization."},"user_name":{"type":"string","maxLength":100,"minLength":2,"title":"User Name","description":"Display name shown in dashboards and audit trails."},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Profile picture URL (e.g., from PropelAuth picture_url property)."},"role":{"$ref":"#/components/schemas/UserRole","description":"Default role within the organization if omitted.","default":"member"},"status":{"$ref":"#/components/schemas/UserStatus","description":"Initial lifecycle status. Use 'pending' for invited users who haven't accepted yet.","default":"active"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Custom key/value metadata stored with the user record."}},"type":"object","required":["email","user_name"],"title":"UserCreateRequest","description":"Payload for creating an organization user.","examples":[{"email":"alice@example.com","role":"member","user_name":"Alice Smith"},{"email":"bob@example.com","metadata":{"department":"Engineering"},"role":"admin","user_name":"Bob Johnson"}]},"UserRole":{"type":"string","enum":["admin","member","viewer"],"title":"UserRole","description":"High-level organization role applied to users.\n\nRoles define the baseline permissions a user has within an organization:\n\n- ADMIN: Full administrative access including user management, billing,\n and organization settings. Can create/modify/delete all resources.\n- MEMBER: Standard user access. Can create and manage their own resources\n (namespaces, collections, clusters) but cannot manage other users or\n organization-level settings.\n- VIEWER: Read-only access. Can view resources and execute retrievers but\n cannot create, modify, or delete any resources."},"UserStatus":{"type":"string","enum":["active","suspended","pending"],"title":"UserStatus","description":"Lifecycle state of an organization user.\n\nStatus values control whether a user can authenticate and access resources:\n\n- ACTIVE: User is fully operational and can authenticate with their API keys.\n- SUSPENDED: User access is temporarily disabled. API keys will not work but\n account data is preserved. Can be reactivated by an admin.\n- PENDING: User invitation has been created but not yet accepted. User cannot\n authenticate until they complete the onboarding flow."},"UserUpdateRequest":{"properties":{"user_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":2},{"type":"null"}],"title":"User Name","description":"Updated display name."},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Updated profile image URL (e.g., custom avatar to override Gravatar)."},"role":{"anyOf":[{"$ref":"#/components/schemas/UserRole"},{"type":"null"}],"description":"Updated organization role."},"status":{"anyOf":[{"$ref":"#/components/schemas/UserStatus"},{"type":"null"}],"description":"Lifecycle status update (active, suspended, pending)."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Replaces metadata with the provided dictionary when set."}},"type":"object","title":"UserUpdateRequest","description":"Partial update payload for a user."},"UuidIndexParams":{"properties":{"type":{"type":"string","title":"Type","default":"uuid"},"is_tenant":{"type":"boolean","title":"Is Tenant","default":false}},"type":"object","title":"UuidIndexParams","description":"Configuration for UUID index."},"ValidateMigrationRequest":{"properties":{"config":{"$ref":"#/components/schemas/MigrationConfig","description":"Migration configuration"}},"type":"object","required":["config"],"title":"ValidateMigrationRequest","description":"Request to validate a migration configuration without creating it."},"ValidateMigrationResponse":{"properties":{"validation_result":{"$ref":"#/components/schemas/ValidationResult","description":"Validation result"},"dependency_graph":{"anyOf":[{"$ref":"#/components/schemas/DependencyGraph"},{"type":"null"}],"description":"Dependency graph if validation passed"},"message":{"type":"string","title":"Message","description":"Human-readable message"}},"type":"object","required":["validation_result","message"],"title":"ValidateMigrationResponse","description":"Response for migration validation.","example":{"message":"Configuration is valid with 1 warning","validation_result":{"errors":[],"estimated_duration_seconds":1800,"estimated_resources":{"collection":5,"taxonomy":2},"valid":true,"warnings":[{"error_code":"RE_EXTRACT_COST_WARNING","message":"RE_EXTRACT migration will reprocess all documents and incur processing costs","severity":"warning"}]}}},"ValidateResult":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether the manifest is valid"},"resources":{"additionalProperties":{"type":"integer"},"type":"object","title":"Resources","description":"Count of each resource type"},"missing_secrets":{"items":{"type":"string"},"type":"array","title":"Missing Secrets","description":"Secret names referenced but not configured"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"Validation errors"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Validation warnings"}},"type":"object","required":["valid"],"title":"ValidateResult","description":"Result of validating a manifest.","examples":[{"errors":[],"missing_secrets":[],"resources":{"buckets":2,"collections":1,"namespaces":1,"retrievers":1},"valid":true,"warnings":[]}]},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValidationResult":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether migration can proceed"},"errors":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Errors","description":"Validation errors"},"warnings":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Warnings","description":"Validation warnings"},"estimated_resources":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/shared__namespaces__migrations__models__ResourceType"},"type":"object","title":"Estimated Resources","description":"Estimated resource counts"},"estimated_duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Duration Seconds","description":"Estimated migration duration"}},"type":"object","required":["valid"],"title":"ValidationResult","description":"Result of pre-flight validation."},"VectorBasedConfig-Input":{"properties":{"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"DEPRECATED: Use feature_uris instead. Canonical feature URI for the vector embedding to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For multi-feature clustering, use feature_uris (plural) instead.","examples":["mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding","mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"]},"feature_uris":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Feature Uris","description":"RECOMMENDED. List of feature URIs to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For single-feature clustering, provide a list with one element. For multi-feature clustering, provide multiple feature URIs. Each feature must exist in all input collections.","examples":[["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"],["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1","mixpeek://image_extractor@v1/embedding"]]},"feature_extractor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Extractor Name","description":"Internal field populated from feature_uri. Do not set manually."},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Internal field populated from feature_uri. Do not set manually."},"output_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Name","description":"Internal field populated from feature_uri. Do not set manually."},"clustering_method":{"$ref":"#/components/schemas/ClusteringAlgorithm","description":"Clustering algorithm to use"},"sample_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sample Size","description":"Number of samples to use for clustering"},"kmeans_parameters":{"anyOf":[{"$ref":"#/components/schemas/KMeansParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Kmeans Parameters","description":"Parameters for K-means clustering (deprecated, use algorithm_params)"},"dbscan_parameters":{"anyOf":[{"$ref":"#/components/schemas/DBSCANParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Dbscan Parameters","description":"Parameters for DBSCAN clustering (deprecated, use algorithm_params)"},"hdbscan_parameters":{"anyOf":[{"$ref":"#/components/schemas/HDBSCANParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hdbscan Parameters","description":"Parameters for HDBSCAN clustering (deprecated, use algorithm_params)"},"algorithm_params":{"anyOf":[{"$ref":"#/components/schemas/KMeansParams"},{"$ref":"#/components/schemas/DBSCANParams"},{"$ref":"#/components/schemas/HDBSCANParams"},{"$ref":"#/components/schemas/AgglomerativeParams"},{"$ref":"#/components/schemas/SpectralParams"},{"$ref":"#/components/schemas/GaussianMixtureParams"},{"$ref":"#/components/schemas/MeanShiftParams"},{"$ref":"#/components/schemas/OPTICSParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Algorithm Params","description":"Algorithm-specific parameters"},"multi_feature_strategy":{"type":"string","enum":["concatenate","independent","weighted"],"title":"Multi Feature Strategy","description":"Strategy for handling multiple feature vectors:\n- concatenate: Combine embeddings into one vector, single clustering\n- independent: Run separate clustering per feature\n- weighted: Learn optimal feature weights","default":"concatenate"},"normalize_features":{"type":"boolean","title":"Normalize Features","description":"Apply L2 normalization to each feature block before concatenation. Prevents feature dominance when combining different modalities. Only applies when multi_feature_strategy='concatenate'.","default":true},"feature_weights":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Feature Weights","description":"Optional per-feature weights (0.0-1.0) for concatenation strategy. Keys are feature URIs, values are weights. Example: {'mixpeek://text@v1/emb': 0.7, 'mixpeek://image@v1/emb': 0.3}. Defaults to equal weights (1.0) if not specified. Only applies when multi_feature_strategy='concatenate'. If multi_feature_strategy='weighted' and this is None, weights are learned automatically using weight_learning_config.","examples":[{"mixpeek://image_extractor@v1/embedding":0.3,"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1":0.7}]},"weight_learning_config":{"anyOf":[{"$ref":"#/components/schemas/WeightLearningConfig"},{"type":"null"}],"description":"Configuration for automatic feature weight learning. Only used when multi_feature_strategy='weighted' and feature_weights is None. If feature_weights is provided, manual weights are used instead of learning. If this is None when learning is needed, default WeightLearningConfig is used.","examples":[{"max_iterations":20,"method":"bayesian","metric":"silhouette","sample_size":5000},{"max_iterations":5,"method":"grid_search","metric":"silhouette"}]},"output_strategy":{"type":"string","enum":["single","per_feature"],"title":"Output Strategy","description":"Output collection creation strategy:\n- single: Create one collection with all feature vectors\n- per_feature: Create separate collections for each feature (for hierarchical taxonomies)","default":"single"},"effective_feature_method":{"type":"string","enum":["mean","median","medoid"],"title":"Effective Feature Method","description":"Method for calculating cluster centroids:\n- mean: Average of all vectors in cluster\n- median: Median vector (robust to outliers)\n- medoid: Actual cluster member closest to centroid","default":"mean"},"enrich_source":{"type":"boolean","title":"Enrich Source","description":"Whether to enrich source documents with cluster_id","default":false}},"type":"object","required":["clustering_method"],"title":"VectorBasedConfig","description":"Configuration for vector-based clustering.\n\nUse canonical feature URIs to specify which vector embeddings to cluster.\nFeature URIs follow the format: mixpeek://{extractor}@{version}/{output}\n\nSupports both single and multi-feature clustering:\n- Single feature: Provide one feature_uri for standard clustering\n- Multi-feature: Provide multiple feature_uris for hybrid clustering\n\nExamples:\n Single feature:\n {\n \"feature_uri\": \"mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding\",\n \"clustering_method\": \"hdbscan\",\n \"sample_size\": 1000\n }\n\n Multi-feature:\n {\n \"feature_uris\": [\n \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"mixpeek://image_extractor@v1/embedding\"\n ],\n \"clustering_method\": \"hdbscan\",\n \"multi_feature_strategy\": \"concatenate\"\n }","examples":[{"algorithm_params":{"min_cluster_size":10,"min_samples":5},"clustering_method":"hdbscan","description":"HDBSCAN clustering with multimodal embeddings","feature_uri":"mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding","sample_size":1000},{"algorithm_params":{"n_clusters":10},"clustering_method":"kmeans","description":"K-means clustering with text embeddings","feature_uri":"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"},{"algorithm_params":{"eps":0.5,"min_samples":5},"clustering_method":"dbscan","description":"DBSCAN clustering with CLIP image embeddings","feature_uri":"mixpeek://clip@v1/image_embedding"}]},"VectorBasedConfig-Output":{"properties":{"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"DEPRECATED: Use feature_uris instead. Canonical feature URI for the vector embedding to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For multi-feature clustering, use feature_uris (plural) instead.","examples":["mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding","mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"]},"feature_uris":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Feature Uris","description":"RECOMMENDED. List of feature URIs to cluster. Format: 'mixpeek://{extractor}@{version}/{output}'. For single-feature clustering, provide a list with one element. For multi-feature clustering, provide multiple feature URIs. Each feature must exist in all input collections.","examples":[["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"],["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1","mixpeek://image_extractor@v1/embedding"]]},"clustering_method":{"$ref":"#/components/schemas/ClusteringAlgorithm","description":"Clustering algorithm to use"},"sample_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sample Size","description":"Number of samples to use for clustering"},"kmeans_parameters":{"anyOf":[{"$ref":"#/components/schemas/KMeansParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Kmeans Parameters","description":"Parameters for K-means clustering (deprecated, use algorithm_params)"},"dbscan_parameters":{"anyOf":[{"$ref":"#/components/schemas/DBSCANParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Dbscan Parameters","description":"Parameters for DBSCAN clustering (deprecated, use algorithm_params)"},"hdbscan_parameters":{"anyOf":[{"$ref":"#/components/schemas/HDBSCANParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hdbscan Parameters","description":"Parameters for HDBSCAN clustering (deprecated, use algorithm_params)"},"algorithm_params":{"anyOf":[{"$ref":"#/components/schemas/KMeansParams"},{"$ref":"#/components/schemas/DBSCANParams"},{"$ref":"#/components/schemas/HDBSCANParams"},{"$ref":"#/components/schemas/AgglomerativeParams"},{"$ref":"#/components/schemas/SpectralParams"},{"$ref":"#/components/schemas/GaussianMixtureParams"},{"$ref":"#/components/schemas/MeanShiftParams"},{"$ref":"#/components/schemas/OPTICSParams"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Algorithm Params","description":"Algorithm-specific parameters"},"multi_feature_strategy":{"type":"string","enum":["concatenate","independent","weighted"],"title":"Multi Feature Strategy","description":"Strategy for handling multiple feature vectors:\n- concatenate: Combine embeddings into one vector, single clustering\n- independent: Run separate clustering per feature\n- weighted: Learn optimal feature weights","default":"concatenate"},"normalize_features":{"type":"boolean","title":"Normalize Features","description":"Apply L2 normalization to each feature block before concatenation. Prevents feature dominance when combining different modalities. Only applies when multi_feature_strategy='concatenate'.","default":true},"feature_weights":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Feature Weights","description":"Optional per-feature weights (0.0-1.0) for concatenation strategy. Keys are feature URIs, values are weights. Example: {'mixpeek://text@v1/emb': 0.7, 'mixpeek://image@v1/emb': 0.3}. Defaults to equal weights (1.0) if not specified. Only applies when multi_feature_strategy='concatenate'. If multi_feature_strategy='weighted' and this is None, weights are learned automatically using weight_learning_config.","examples":[{"mixpeek://image_extractor@v1/embedding":0.3,"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1":0.7}]},"weight_learning_config":{"anyOf":[{"$ref":"#/components/schemas/WeightLearningConfig"},{"type":"null"}],"description":"Configuration for automatic feature weight learning. Only used when multi_feature_strategy='weighted' and feature_weights is None. If feature_weights is provided, manual weights are used instead of learning. If this is None when learning is needed, default WeightLearningConfig is used.","examples":[{"max_iterations":20,"method":"bayesian","metric":"silhouette","sample_size":5000},{"max_iterations":5,"method":"grid_search","metric":"silhouette"}]},"output_strategy":{"type":"string","enum":["single","per_feature"],"title":"Output Strategy","description":"Output collection creation strategy:\n- single: Create one collection with all feature vectors\n- per_feature: Create separate collections for each feature (for hierarchical taxonomies)","default":"single"},"effective_feature_method":{"type":"string","enum":["mean","median","medoid"],"title":"Effective Feature Method","description":"Method for calculating cluster centroids:\n- mean: Average of all vectors in cluster\n- median: Median vector (robust to outliers)\n- medoid: Actual cluster member closest to centroid","default":"mean"},"enrich_source":{"type":"boolean","title":"Enrich Source","description":"Whether to enrich source documents with cluster_id","default":false}},"type":"object","required":["clustering_method"],"title":"VectorBasedConfig","description":"Configuration for vector-based clustering.\n\nUse canonical feature URIs to specify which vector embeddings to cluster.\nFeature URIs follow the format: mixpeek://{extractor}@{version}/{output}\n\nSupports both single and multi-feature clustering:\n- Single feature: Provide one feature_uri for standard clustering\n- Multi-feature: Provide multiple feature_uris for hybrid clustering\n\nExamples:\n Single feature:\n {\n \"feature_uri\": \"mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding\",\n \"clustering_method\": \"hdbscan\",\n \"sample_size\": 1000\n }\n\n Multi-feature:\n {\n \"feature_uris\": [\n \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"mixpeek://image_extractor@v1/embedding\"\n ],\n \"clustering_method\": \"hdbscan\",\n \"multi_feature_strategy\": \"concatenate\"\n }","examples":[{"algorithm_params":{"min_cluster_size":10,"min_samples":5},"clustering_method":"hdbscan","description":"HDBSCAN clustering with multimodal embeddings","feature_uri":"mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding","sample_size":1000},{"algorithm_params":{"n_clusters":10},"clustering_method":"kmeans","description":"K-means clustering with text embeddings","feature_uri":"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1"},{"algorithm_params":{"eps":0.5,"min_samples":5},"clustering_method":"dbscan","description":"DBSCAN clustering with CLIP image embeddings","feature_uri":"mixpeek://clip@v1/image_embedding"}]},"VectorDataType":{"type":"string","enum":["float32","uint8"],"title":"VectorDataType","description":"Vector data type."},"VectorIndex":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"OPTIONAL. Qdrant named vector identifier. If not provided, auto-derived from inference_service_id using the same conversion as inference_name (org/model -> org__model with hyphens as underscores). This enables cross-extractor compatibility: extractors using the same model will share the same named vector in Qdrant, allowing direct vector search across collections without fusion logic.","examples":["intfloat__multilingual_e5_large_instruct","google__siglip_base_patch16_224","jinaai__jina_embeddings_v2_base_code"]},"description":{"type":"string","minLength":10,"title":"Description","description":"REQUIRED. Human-readable description of what this vector index represents. Explain the content type, use cases, and search characteristics. Shown in API documentation and collection metadata. Be specific about what embeddings are stored here.","examples":["Dense vector embedding for text content using E5-Large model","Video segment embeddings for semantic visual search","Sparse keyword expansion embeddings for explainable search"]},"dimensions":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Dimensions","description":"Number of vector dimensions. REQUIRED for DENSE vectors (e.g., 1024 for E5-Large, 1408 for multimodal). NOT REQUIRED for SPARSE vectors (dimensions determined dynamically). Must match the output dimensions of the inference service. Cannot be changed after index creation without recreating the collection.","examples":[1024,1408,768,512]},"type":{"$ref":"#/components/schemas/VectorType","description":"REQUIRED. Vector storage format type. Determines how vectors are stored and searched in Qdrant. Use DENSE for traditional embeddings (most common), SPARSE for keyword-based models like SPLADE, MULTI_DENSE for late-interaction models like ColBERT. Must match the output format of your inference service.","examples":["dense","sparse","multi_dense"]},"distance":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Distance","description":"Distance metric for similarity search. OPTIONAL - defaults to 'cosine' (normalized dot product). Options: 'cosine' (most common, normalized), 'dot' (raw dot product), 'euclidean' (L2 distance), 'manhattan' (L1 distance). Cosine recommended for most embeddings as it's scale-invariant. Must match the metric your model was trained with.","default":"cosine","examples":["cosine","dot","euclidean"]},"datatype":{"anyOf":[{"$ref":"#/components/schemas/VectorDataType"},{"type":"null"}],"description":"Data type for storing vector values. OPTIONAL - defaults to FLOAT32 (standard precision). Use FLOAT32 for general use (4 bytes per dimension). Use FLOAT16 to save 50% storage with minimal quality loss. Use UINT8 for maximum compression (quantization, ~2% quality loss). Lower precision = smaller storage + faster search, slightly lower accuracy.","default":"float32","examples":["float32","float16","uint8"]},"on_disk":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"On Disk","description":"OPTIONAL. If true, vectors stored on disk instead of RAM. Defaults to true for memory efficiency. Set to false for faster search with higher memory usage. Trade-off: on_disk=true saves ~95% RAM but ~10x slower search. Recommended to keep default (true) unless RAM is abundant and low latency critical."},"supported_inputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/BucketSchemaFieldType"},"type":"array"},{"type":"null"}],"title":"Supported Inputs","description":"OPTIONAL. List of bucket schema field types this vector can process. Validates that input fields are compatible with this index. Examples: TEXT and STRING for text embeddings, VIDEO and IMAGE for multimodal embeddings, DOCUMENT for PDF extractors. Used for validation during collection creation.","examples":[["text","string"],["video","image"],["document"]]},"inference_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Name","description":"DEPRECATED: Use inference_service_id instead. Identifier of the inference service to generate embeddings. Must reference a valid inference service registered in the system. Examples: 'multilingual_e5_large_instruct_v1' for text, 'vertex_multimodal_embedding' for video, 'laion_clip_vit_l_14_v1' for images. This determines which model creates the vectors during ingestion. Cannot be changed after collection creation.","examples":["multilingual_e5_large_instruct_v1","vertex_multimodal_embedding","laion_clip_vit_l_14_v1","openai_text_embedding_3_small"]},"inference_service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Service Id","description":"RECOMMENDED. Service ID in org/name format (e.g., 'intfloat/e5-large'). When set, dimensions and distance are automatically derived from the registry. This is the canonical identifier for cross-plugin compatibility. Plugins using the same service_id can search across each other's vectors. Takes precedence over inference_name when both are set.","examples":["intfloat/e5-large","google/vertex-multimodal","google/siglip","jinaai/jina-code-v2"]},"purpose":{"anyOf":[{"$ref":"#/components/schemas/VectorPurpose"},{"type":"null"}],"description":"RECOMMENDED. Semantic purpose of this vector index. Enables pipelines to look up vector configs by purpose (text, code, image) without needing to know the specific inference_service_id. This provides automatic configuration - the pipeline just says 'give me the text vector' and gets the correct column name. If not specified, pipeline must use inference_service_id lookup.","examples":["text","code","image","multimodal"]},"vector_name_override":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vector Name Override","description":"OPTIONAL. Override for Qdrant named vector identifier. When set, this value is used as the Qdrant vector name instead of auto-deriving from inference_service_id. This enables multiple vectors from the same embedding model with different storage names. The inference_service_id is still used for cross-extractor compatibility checking, but storage uses this custom name. Use case: A single extractor producing N vectors (e.g., title_embedding, body_embedding) using the same model but needing separate storage.","examples":["title_embedding","body_embedding","summary_embedding"]}},"type":"object","required":["description","type"],"title":"VectorIndex","description":"Configuration for a single vector index in Qdrant.\n\nDefines the fully-qualified vector index including storage name, dimensions,\ndistance metric, and inference service. This is the actual index that gets\ncreated in Qdrant and used for vector similarity search.\n\nKey Concepts:\n - The `name` field is the FULL qualified name used as the Qdrant collection name\n - Format: {extractor}_{version}_{output} (e.g., \"text_extractor_v1_embedding\")\n - This ensures namespace isolation between extractors and versions\n - Different from VectorIndexDefinition.name which is the short user-facing name\n\nUse Cases:\n - Define vector storage configuration for feature extractors\n - Specify inference service and model parameters\n - Configure distance metrics for similarity search\n - Set storage optimization (on-disk for large vectors)\n\nRequirements:\n - name: REQUIRED - Must be unique across all extractors in namespace\n - description: REQUIRED - Explain what this vector represents\n - dimensions: REQUIRED for DENSE vectors, OPTIONAL for SPARSE\n - type: REQUIRED - Must match VectorType enum\n - inference_name: REQUIRED - Must reference a valid inference service","examples":[{"datatype":"float32","description":"Dense vector embedding for text content using E5-Large multilingual model. Optimized for semantic search across 100+ languages.","dimensions":1024,"distance":"cosine","inference_name":"multilingual_e5_large_instruct_v1","name":"text_extractor_v1_embedding","supported_inputs":["text","string"],"type":"dense"},{"datatype":"float32","description":"Dense vector embeddings for video segments using Google's multimodal model. Supports visual semantic search.","dimensions":1408,"distance":"cosine","inference_name":"vertex_multimodal_embedding","name":"multimodal_extractor_v1_video_embedding","supported_inputs":["video","image"],"type":"dense"},{"datatype":"float32","description":"Dense vector embeddings for images using SigLIP model. Supports visual semantic search.","dimensions":768,"distance":"cosine","inference_name":"siglip_base_v1","name":"image_extractor_v1_embedding","supported_inputs":["image"],"type":"dense"},{"description":"Title embedding using E5-Large - same model as body but stored separately.","inference_service_id":"intfloat/multilingual-e5-large-instruct","type":"dense","vector_name_override":"title_embedding"},{"description":"Body embedding using E5-Large - same model as title but stored separately.","inference_service_id":"intfloat/multilingual-e5-large-instruct","type":"dense","vector_name_override":"body_embedding"}]},"VectorIndexDefinition":{"properties":{"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Full feature URI for this vector index. Format: mixpeek://{extractor}@{version}/{output_name}. Populated at collection creation time. Use this URI in retriever feature_filter stages.","examples":["mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1","mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding"]},"name":{"type":"string","minLength":1,"title":"Name","description":"REQUIRED. Short user-facing output name used in feature URIs. This is NOT the Qdrant collection name - it's the clean identifier for this output. Format: Simple snake_case name (e.g., 'embedding', 'video_embedding', 'sparse_embedding'). Used in feature URIs: mixpeek://{extractor}@{version}/{THIS_NAME}. Must be unique within this extractor's outputs.","examples":["embedding","video_embedding","transcription_embedding","sparse_embedding"]},"description":{"type":"string","minLength":10,"title":"Description","description":"REQUIRED. Human-readable description of this vector output. Explain what content this output embeds and when to use it. Appears in API documentation and helps users choose the right feature URI. Be specific about the embedding type and use cases.","examples":["Vector index for video segment embeddings","Dense text embeddings for semantic search","Sparse keyword embeddings for explainable retrieval"]},"type":{"type":"string","enum":["single","multi"],"title":"Type","description":"REQUIRED. Index type - 'single' or 'multi'. 'single': One vector per document (most common). Use for standard embeddings. 'multi': Multiple named vectors per document (rare). Use for hybrid/ensemble. Determines whether 'index' field contains VectorIndex or MultiVectorIndex.","examples":["single","multi"]},"index":{"anyOf":[{"$ref":"#/components/schemas/VectorIndex"},{"$ref":"#/components/schemas/MultiVectorIndex"}],"title":"Index","description":"REQUIRED. Nested index configuration. VectorIndex if type='single' (most common case). MultiVectorIndex if type='multi' (rare, for hybrid search). Contains the full storage configuration including Qdrant collection name, dimensions, distance metric, and inference service."}},"type":"object","required":["name","description","type","index"],"title":"VectorIndexDefinition","description":"Complete vector index definition that can be either single or multi-vector.\n\nThis is the USER-FACING representation that appears in feature extractor definitions\nand API responses. It wraps a VectorIndex (or MultiVectorIndex) and adds metadata.\n\nKey Concepts - Two-Name System:\n - VectorIndexDefinition.name: SHORT user-facing name (e.g., \"embedding\")\n Used in feature URIs: mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\n ^^^^^^^^^^\n\n - VectorIndex.name: FULL storage name (e.g., \"text_extractor_v1_embedding\")\n Used as Qdrant collection name for namespace isolation\n\nThis two-level naming allows clean URIs while preventing storage collisions.\n\nUse Cases:\n - Define extractor outputs in feature extractor definitions\n - Expose available vector indexes in collection metadata\n - Enable feature URI resolution (short name ā†’ full storage name)\n\nRequirements:\n - name: REQUIRED - Short output name for feature URIs\n - description: REQUIRED - Explain what this output produces\n - type: REQUIRED - \"single\" (most common) or \"multi\" (rare)\n - index: REQUIRED - Nested VectorIndex or MultiVectorIndex\n - feature_uri: OPTIONAL - Populated at collection creation time","examples":[{"description":"Vector index for text embeddings using E5-Large model.","index":{"datatype":"float32","description":"Dense vector embedding for text content","dimensions":1024,"distance":"cosine","inference_name":"multilingual_e5_large_instruct_v1","name":"text_extractor_v1_embedding","supported_inputs":["text","string"],"type":"dense"},"name":"embedding","type":"single"},{"description":"Vector index for video segment embeddings using multimodal model.","index":{"datatype":"float32","description":"Dense vector embeddings for video segments","dimensions":1408,"distance":"cosine","inference_name":"vertex_multimodal_embedding","name":"multimodal_extractor_v1_video_embedding","supported_inputs":["video","image"],"type":"dense"},"name":"video_embedding","type":"single"},{"description":"Hybrid dense + sparse embeddings for enhanced retrieval.","index":{"description":"Combined dense and sparse embeddings","name":"hybrid_extractor_v1_multi","vectors":{"dense":{"description":"Dense semantic embedding","dimensions":1024,"distance":"cosine","inference_name":"multilingual_e5_large_instruct_v1","name":"hybrid_v1_dense","type":"dense"},"sparse":{"description":"Sparse keyword embedding","distance":"dot","inference_name":"splade_plus_plus_v1","name":"hybrid_v1_sparse","type":"sparse"}}},"name":"hybrid_embedding","type":"multi"}]},"VectorPurpose":{"type":"string","enum":["text","code","image","multimodal","video","audio","sparse"],"title":"VectorPurpose","description":"Semantic purpose of a vector index.\n\nUsed by pipelines to look up vector configs by purpose without\nneeding to know the specific inference_service_id."},"VectorType":{"type":"string","enum":["dense","sparse","multi_dense"],"title":"VectorType","description":"Vector types supported by the Mixpeek system.\n\nDefines the storage format and structure of embeddings in Qdrant.\n\nValues:\n DENSE: Traditional float array embeddings (e.g., [0.1, 0.2, 0.3]).\n Most common format. Used by: text_extractor, multimodal_extractor, image_extractor.\n Storage: ~4KB per 1024-dim vector. Fast cosine/dot similarity search.\n\n SPARSE: Index-value pairs for sparse embeddings (e.g., SPLADE, BM25).\n Only stores non-zero dimensions. Format: {indices: [1,5,9], values: [0.8,0.6,0.4]}.\n Storage: ~20KB. Keyword-based semantic search.\n\n MULTI_DENSE: List of dense vectors for late interaction models (e.g., ColBERT).\n Each document has multiple embeddings. Format: [[0.1,0.2], [0.3,0.4], ...].\n Storage: ~500KB. High-precision retrieval.\n\nExamples:\n - DENSE for general semantic search (text_extractor, multimodal_extractor)\n - SPARSE for keyword expansion and explainability\n - MULTI_DENSE for maximum precision retrieval"},"VerifyPasswordRequest":{"properties":{"password":{"type":"string","minLength":1,"title":"Password","description":"The password to verify against the retriever's password"}},"type":"object","required":["password"],"title":"VerifyPasswordRequest","description":"Request to verify password for a password-protected retriever."},"VerifyPasswordResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"Whether the provided password is valid"},"public_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Api Key","description":"DEPRECATED: API keys are no longer required. After password verification, call the execute endpoint directly."}},"type":"object","required":["valid"],"title":"VerifyPasswordResponse","description":"Response from password verification."},"WebScraperExtractorParams":{"properties":{"extractor_type":{"type":"string","const":"web_scraper","title":"Extractor Type","description":"Discriminator field for parameter type identification.","default":"web_scraper"},"max_depth":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Max Depth","description":"Maximum link depth to crawl. 0=seed page only, 1=seed+direct links, etc. Default: 2. Max: 10.","default":2},"max_pages":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Max Pages","description":"Maximum pages to crawl. Default: 50. Max: 500.","default":50},"crawl_timeout":{"type":"integer","maximum":3600.0,"minimum":10.0,"title":"Crawl Timeout","description":"Maximum total time for crawling in seconds. Default: 300 (5 minutes). Increase for large sites with many pages. Max: 3600 (1 hour).","default":300},"crawl_mode":{"$ref":"#/components/schemas/CrawlMode","description":"Crawl strategy. DETERMINISTIC: BFS all links (predictable). SEMANTIC: LLM-guided, prioritizes relevant pages (requires crawl_goal).","default":"deterministic"},"crawl_goal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Crawl Goal","description":"Goal for semantic crawling. Only used when crawl_mode=SEMANTIC. Example: 'Find all S3 API documentation and examples'"},"render_strategy":{"$ref":"#/components/schemas/RenderStrategy","description":"How to render pages. AUTO (default): tries static, falls back to JS. STATIC: fast HTTP fetch. JAVASCRIPT: Playwright browser for SPAs.","default":"auto"},"include_patterns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include Patterns","description":"Regex patterns for URLs to include. Example: ['/docs/', '/api/']"},"exclude_patterns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Exclude Patterns","description":"Regex patterns for URLs to exclude. Example: ['/blog/', '\\.pdf$']"},"chunk_strategy":{"$ref":"#/components/schemas/ChunkStrategy","description":"How to split page content. NONE: one chunk per page. SENTENCES/PARAGRAPHS: semantic boundaries. WORDS/CHARACTERS: fixed size chunks.","default":"none"},"chunk_size":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Chunk Size","description":"Target size for each chunk (in units of chunk_strategy).","default":500},"chunk_overlap":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Chunk Overlap","description":"Overlap between chunks to preserve context.","default":50},"document_id_strategy":{"$ref":"#/components/schemas/DocumentIdStrategy","description":"How to generate document IDs. URL (default): stable across re-crawls. POSITION: order-based. CONTENT: deduplicates identical content.","default":"url"},"generate_text_embeddings":{"type":"boolean","title":"Generate Text Embeddings","description":"Generate E5 embeddings for text content.","default":true},"generate_code_embeddings":{"type":"boolean","title":"Generate Code Embeddings","description":"Generate Jina code embeddings for code blocks.","default":true},"generate_image_embeddings":{"type":"boolean","title":"Generate Image Embeddings","description":"Generate SigLIP embeddings for images/figures.","default":true},"generate_structure_embeddings":{"type":"boolean","title":"Generate Structure Embeddings","description":"Generate DINOv2 visual structure embeddings for layout comparison.","default":true},"response_shape":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Response Shape","description":"Optional structured extraction schema. Natural language or JSON schema. Example: 'Extract API version, deprecated methods, and example code'"},"llm_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Provider","description":"LLM provider for structured extraction: openai, google, anthropic"},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model","description":"LLM model for structured extraction."},"llm_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Api Key","description":"API key for LLM operations (BYOK - Bring Your Own Key). Supports:\n- Direct key: 'sk-proj-abc123...'\n- Secret reference: '{{SECRET.openai_api_key}}'\n\nWhen using secret reference, the key is loaded from your organization's secrets vault at runtime. Store secrets via POST /v1/organizations/secrets.\n\nIf not provided, uses Mixpeek's default API keys."},"max_retries":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Max Retries","description":"Maximum retry attempts for failed HTTP requests. Uses exponential backoff with jitter. Default: 3.","default":3},"retry_base_delay":{"type":"number","maximum":30.0,"minimum":0.1,"title":"Retry Base Delay","description":"Base delay in seconds for retry backoff. Actual delay = base * 2^attempt + jitter. Default: 1.0.","default":1.0},"retry_max_delay":{"type":"number","maximum":300.0,"minimum":1.0,"title":"Retry Max Delay","description":"Maximum delay in seconds between retries. Default: 30.","default":30.0},"respect_retry_after":{"type":"boolean","title":"Respect Retry After","description":"Respect Retry-After header from 429/503 responses. If False, uses exponential backoff instead. Default: True.","default":true},"proxies":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Proxies","description":"List of proxy URLs for rotation. Supports formats: 'http://host:port', 'http://user:pass@host:port', 'socks5://host:port'. Proxies rotate on errors or every N requests."},"rotate_proxy_on_error":{"type":"boolean","title":"Rotate Proxy On Error","description":"Rotate to next proxy when request fails. Default: True.","default":true},"rotate_proxy_every_n_requests":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Rotate Proxy Every N Requests","description":"Rotate proxy every N requests (0 = disabled). Useful for avoiding IP-based rate limits. Default: 0 (disabled).","default":0},"captcha_service_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Captcha Service Provider","description":"Captcha solving service provider: '2captcha', 'anti-captcha', 'capsolver'. If not set, captcha pages are skipped gracefully."},"captcha_service_api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Captcha Service Api Key","description":"API key for captcha solving service. Supports secret reference: '{{SECRET.captcha_api_key}}'. Required if captcha_service_provider is set."},"detect_captcha":{"type":"boolean","title":"Detect Captcha","description":"Detect captcha challenges (Cloudflare, reCAPTCHA, hCaptcha). If detected and no solver configured, page is skipped. Default: True.","default":true},"persist_cookies":{"type":"boolean","title":"Persist Cookies","description":"Persist cookies across requests within a crawl session. Useful for sites requiring authentication. Default: True.","default":true},"custom_headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Custom Headers","description":"Custom HTTP headers to include in all requests. Example: {'Authorization': 'Bearer token', 'X-Custom': 'value'}"},"delay_between_requests":{"type":"number","maximum":60.0,"minimum":0.0,"title":"Delay Between Requests","description":"Delay in seconds between consecutive requests. Useful for polite crawling and avoiding rate limits. Default: 0 (no delay).","default":0.0}},"type":"object","title":"WebScraperExtractorParams","description":"Parameters for the web scraper extractor.\n\nThe web scraper extractor crawls websites and extracts content with three types\nof embeddings for comprehensive multimodal search:\n\n**Embedding Types:**\n- Text (E5-Large): 1024D embeddings for page content\n- Code (Jina Code): 768D embeddings for code blocks\n- Images (SigLIP): 768D semantic embeddings for figures/screenshots\n- Images (DINOv2): 768D structure embeddings for visual layout comparison\n\n**Crawl Modes:**\n- DETERMINISTIC: BFS following all links (default, predictable)\n- SEMANTIC: LLM-guided, prioritizes pages matching crawl_goal\n\n**Rendering Strategies:**\n- STATIC: Fast HTTP fetch (default, works for most sites)\n- JAVASCRIPT: Playwright browser for SPAs (React/Vue/Angular)\n- AUTO: Tries static, falls back to JS if content too short\n\n**Use Cases:**\n- Documentation freshness: Crawl docs, compare against course content\n- Job board ingestion: Extract job listings with structured data\n- Knowledge base building: Convert websites to searchable collections\n- Code example indexing: Find API usage patterns across docs","examples":[{"chunk_size":3,"chunk_strategy":"paragraphs","description":"Documentation site crawl","extractor_type":"web_scraper","max_depth":3,"max_pages":100},{"description":"Job board extraction","extractor_type":"web_scraper","max_depth":1,"max_pages":50,"render_strategy":"auto","response_shape":"Extract job title, department, location, and requirements"},{"crawl_goal":"Find all S3 upload examples and API documentation","crawl_mode":"semantic","description":"Semantic crawl for API docs","extractor_type":"web_scraper","generate_code_embeddings":true,"max_pages":200},{"delay_between_requests":0.5,"description":"Large-scale catalogue with resilience","extractor_type":"web_scraper","max_depth":5,"max_pages":10000,"max_retries":5,"respect_retry_after":true},{"description":"Protected site with proxy rotation","extractor_type":"web_scraper","max_pages":5000,"persist_cookies":true,"proxies":["http://proxy1.example.com:8080","http://proxy2.example.com:8080"],"rotate_proxy_every_n_requests":50,"rotate_proxy_on_error":true}]},"Webhook-Input":{"properties":{"webhook_id":{"type":"string","pattern":"^wh_[a-fA-F0-9]{16}$","title":"Webhook Id","description":"Unique identifier for the webhook. Auto-generated with 'wh_' prefix followed by secure random token. Format: wh_{16-character hex}. Used for API operations and event tracking.","examples":["wh_abc123def4567890","wh_1234567890abcdef"]},"webhook_name":{"type":"string","maxLength":200,"minLength":1,"title":"Webhook Name","description":"REQUIRED. Human-readable name for the webhook. Displayed in dashboards, logs, and notification metadata. Should describe the webhook's purpose or destination. Format: 1-200 characters.","examples":["Slack Engineering Alerts","External System Integration","Audit Trail Logger","Production Monitoring"]},"internal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Internal Id","description":"Organization internal identifier for multi-tenancy scoping. All webhook operations are scoped to this organization. Excluded from API responses for security. Format: int_{24-character secure token}."},"event_types":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","minItems":1,"title":"Event Types","description":"REQUIRED. List of event types that trigger this webhook. When any of these events occur, notifications are sent to all channels. Must contain at least one event type. Common patterns: - ['object.created', 'object.updated'] for object lifecycle tracking - ['cluster.execution.completed', 'cluster.execution.failed'] for job monitoring - ['*'] for all events (use cautiously, high volume)","examples":[["object.created","object.updated","object.deleted"],["cluster.execution.completed","cluster.execution.failed"],["collection.documents.written"]]},"channels":{"items":{"$ref":"#/components/schemas/WebhookChannel-Input"},"type":"array","minItems":1,"title":"Channels","description":"REQUIRED. List of notification channels for event delivery. When an event occurs, notifications are sent to ALL configured channels. Must contain at least one channel. Multiple channels provide redundancy and multi-audience delivery. Example: Send to both Slack (team) and email (manager) for critical events."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the webhook is currently active and should send notifications. True: Events trigger notifications to channels. False: Webhook is paused, no notifications sent but config preserved. Use to temporarily disable webhooks without losing configuration. Default: True","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"UTC timestamp of the most recent webhook update. Updated automatically when event_types, channels, or is_active changes. Tracks configuration modifications. Format: ISO 8601 datetime."}},"type":"object","required":["webhook_name","event_types","channels"],"title":"Webhook","description":"Configured webhook subscription for organization event notifications.\n\nWebhooks enable real-time notifications when events occur in the system.\nEach webhook subscribes to specific event types and delivers notifications\nvia one or more configured channels (Slack, email, HTTP).\n\nWebhook Lifecycle:\n 1. Created with event_types and channels configured\n 2. is_active=True enables notification delivery\n 3. Events matching event_types trigger notifications to all channels\n 4. is_active=False temporarily pauses notifications without deletion\n 5. Webhook can be updated to add/remove event types or channels\n 6. Permanent deletion removes the webhook configuration\n\nUse Cases:\n - Integrate Mixpeek events with external systems via HTTP webhooks\n - Notify teams in Slack when ingestion jobs complete\n - Send email alerts when critical failures occur\n - Trigger automated workflows based on state changes\n - Maintain audit trails by forwarding events to SIEM systems\n\nBest Practices:\n - Subscribe only to events you need (reduces noise)\n - Use descriptive webhook_name for identification\n - Configure multiple channels for critical events (redundancy)\n - Set is_active=False to temporarily disable without losing config\n - Monitor webhook delivery failures via last_error tracking","examples":[{"channels":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"}}],"created_at":"2025-01-01T00:00:00Z","description":"Slack notifications for object lifecycle","event_types":["object.created","object.updated","object.deleted"],"is_active":true,"updated_at":"2025-01-01T00:00:00Z","webhook_id":"wh_abc123def4","webhook_name":"Engineering Slack Alerts"},{"channels":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"}},{"channel":"email","configs":{"recipients":["oncall@example.com"],"subject_template":"CRITICAL: {event_type}"}}],"created_at":"2025-01-01T00:00:00Z","description":"Multi-channel alerts for cluster failures","event_types":["cluster.execution.failed","trigger.execution.failed"],"is_active":true,"updated_at":"2025-01-15T10:30:00Z","webhook_id":"wh_xyz789uvw0","webhook_name":"Production Monitoring"},{"channels":[{"channel":"webhook","configs":{"headers":{"Authorization":"Bearer secret123"},"method":"POST","url":"https://siem.company.com/webhooks/mixpeek"}}],"created_at":"2025-01-01T00:00:00Z","description":"External system integration via HTTP webhook","event_types":["object.created","object.updated","object.deleted","collection.created","collection.deleted"],"is_active":true,"updated_at":"2025-01-01T00:00:00Z","webhook_id":"wh_int123ext4","webhook_name":"SIEM Audit Trail"}]},"Webhook-Output":{"properties":{"webhook_id":{"type":"string","pattern":"^wh_[a-fA-F0-9]{16}$","title":"Webhook Id","description":"Unique identifier for the webhook. Auto-generated with 'wh_' prefix followed by secure random token. Format: wh_{16-character hex}. Used for API operations and event tracking.","examples":["wh_abc123def4567890","wh_1234567890abcdef"]},"webhook_name":{"type":"string","maxLength":200,"minLength":1,"title":"Webhook Name","description":"REQUIRED. Human-readable name for the webhook. Displayed in dashboards, logs, and notification metadata. Should describe the webhook's purpose or destination. Format: 1-200 characters.","examples":["Slack Engineering Alerts","External System Integration","Audit Trail Logger","Production Monitoring"]},"event_types":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","minItems":1,"title":"Event Types","description":"REQUIRED. List of event types that trigger this webhook. When any of these events occur, notifications are sent to all channels. Must contain at least one event type. Common patterns: - ['object.created', 'object.updated'] for object lifecycle tracking - ['cluster.execution.completed', 'cluster.execution.failed'] for job monitoring - ['*'] for all events (use cautiously, high volume)","examples":[["object.created","object.updated","object.deleted"],["cluster.execution.completed","cluster.execution.failed"],["collection.documents.written"]]},"channels":{"items":{"$ref":"#/components/schemas/WebhookChannel-Output"},"type":"array","minItems":1,"title":"Channels","description":"REQUIRED. List of notification channels for event delivery. When an event occurs, notifications are sent to ALL configured channels. Must contain at least one channel. Multiple channels provide redundancy and multi-audience delivery. Example: Send to both Slack (team) and email (manager) for critical events."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the webhook is currently active and should send notifications. True: Events trigger notifications to channels. False: Webhook is paused, no notifications sent but config preserved. Use to temporarily disable webhooks without losing configuration. Default: True","default":true},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"UTC timestamp of the most recent webhook update. Updated automatically when event_types, channels, or is_active changes. Tracks configuration modifications. Format: ISO 8601 datetime."}},"type":"object","required":["webhook_name","event_types","channels"],"title":"Webhook","description":"Configured webhook subscription for organization event notifications.\n\nWebhooks enable real-time notifications when events occur in the system.\nEach webhook subscribes to specific event types and delivers notifications\nvia one or more configured channels (Slack, email, HTTP).\n\nWebhook Lifecycle:\n 1. Created with event_types and channels configured\n 2. is_active=True enables notification delivery\n 3. Events matching event_types trigger notifications to all channels\n 4. is_active=False temporarily pauses notifications without deletion\n 5. Webhook can be updated to add/remove event types or channels\n 6. Permanent deletion removes the webhook configuration\n\nUse Cases:\n - Integrate Mixpeek events with external systems via HTTP webhooks\n - Notify teams in Slack when ingestion jobs complete\n - Send email alerts when critical failures occur\n - Trigger automated workflows based on state changes\n - Maintain audit trails by forwarding events to SIEM systems\n\nBest Practices:\n - Subscribe only to events you need (reduces noise)\n - Use descriptive webhook_name for identification\n - Configure multiple channels for critical events (redundancy)\n - Set is_active=False to temporarily disable without losing config\n - Monitor webhook delivery failures via last_error tracking","examples":[{"channels":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"}}],"created_at":"2025-01-01T00:00:00Z","description":"Slack notifications for object lifecycle","event_types":["object.created","object.updated","object.deleted"],"is_active":true,"updated_at":"2025-01-01T00:00:00Z","webhook_id":"wh_abc123def4","webhook_name":"Engineering Slack Alerts"},{"channels":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"}},{"channel":"email","configs":{"recipients":["oncall@example.com"],"subject_template":"CRITICAL: {event_type}"}}],"created_at":"2025-01-01T00:00:00Z","description":"Multi-channel alerts for cluster failures","event_types":["cluster.execution.failed","trigger.execution.failed"],"is_active":true,"updated_at":"2025-01-15T10:30:00Z","webhook_id":"wh_xyz789uvw0","webhook_name":"Production Monitoring"},{"channels":[{"channel":"webhook","configs":{"headers":{"Authorization":"Bearer secret123"},"method":"POST","url":"https://siem.company.com/webhooks/mixpeek"}}],"created_at":"2025-01-01T00:00:00Z","description":"External system integration via HTTP webhook","event_types":["object.created","object.updated","object.deleted","collection.created","collection.deleted"],"is_active":true,"updated_at":"2025-01-01T00:00:00Z","webhook_id":"wh_int123ext4","webhook_name":"SIEM Audit Trail"}]},"WebhookChannel-Input":{"properties":{"channel":{"$ref":"#/components/schemas/NotificationChannel","description":"REQUIRED. The notification channel type for delivery. Determines which delivery mechanism is used (email, Slack, webhook). Must match the type of the configs field."},"configs":{"anyOf":[{"$ref":"#/components/schemas/EmailConfig"},{"$ref":"#/components/schemas/SlackConfig"},{"$ref":"#/components/schemas/WebhookConfig"}],"title":"Configs","description":"REQUIRED. Channel-specific configuration for notification delivery. Type depends on the channel field: - EmailConfig for EMAIL channel (recipients, subject template, etc.) - SlackConfig for SLACK channel (workspace, channel, bot token) - WebhookConfig for WEBHOOK channel (URL, headers, auth). See respective config models for detailed field requirements."}},"type":"object","required":["channel","configs"],"title":"WebhookChannel","description":"Notification channel configuration for webhook delivery.\n\nDefines how and where webhook event notifications should be delivered.\nEach webhook can have multiple channels configured for redundancy or\ndifferent notification audiences.\n\nSupported Channels:\n - EMAIL: Send notifications via email to specified recipients\n - SLACK: Post messages to Slack channels or direct messages\n - WEBHOOK: HTTP POST to external endpoints (standard webhooks)\n\nUse Cases:\n - Route critical alerts to Slack and email simultaneously\n - Send audit trail events to external webhook endpoints\n - Notify team members via email for object lifecycle events\n - Post cluster completion status to Slack channels\n\nRequirements:\n - Channel type must match the config type (discriminated union)\n - Each config must have valid credentials/endpoints configured\n - Channel configs are validated at webhook creation time","examples":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"},"description":"Slack notification channel"},{"channel":"email","configs":{"recipients":["team@example.com","admin@example.com"],"subject_template":"Mixpeek Alert: {event_type}"},"description":"Email notification channel"},{"channel":"webhook","configs":{"headers":{"Authorization":"Bearer token123"},"method":"POST","url":"https://api.example.com/webhooks/mixpeek"},"description":"HTTP webhook channel"}]},"WebhookChannel-Output":{"properties":{"channel":{"$ref":"#/components/schemas/NotificationChannel","description":"REQUIRED. The notification channel type for delivery. Determines which delivery mechanism is used (email, Slack, webhook). Must match the type of the configs field."},"configs":{"anyOf":[{"$ref":"#/components/schemas/EmailConfig"},{"$ref":"#/components/schemas/SlackConfig"},{"$ref":"#/components/schemas/WebhookConfig"}],"title":"Configs","description":"REQUIRED. Channel-specific configuration for notification delivery. Type depends on the channel field: - EmailConfig for EMAIL channel (recipients, subject template, etc.) - SlackConfig for SLACK channel (workspace, channel, bot token) - WebhookConfig for WEBHOOK channel (URL, headers, auth). See respective config models for detailed field requirements."}},"type":"object","required":["channel","configs"],"title":"WebhookChannel","description":"Notification channel configuration for webhook delivery.\n\nDefines how and where webhook event notifications should be delivered.\nEach webhook can have multiple channels configured for redundancy or\ndifferent notification audiences.\n\nSupported Channels:\n - EMAIL: Send notifications via email to specified recipients\n - SLACK: Post messages to Slack channels or direct messages\n - WEBHOOK: HTTP POST to external endpoints (standard webhooks)\n\nUse Cases:\n - Route critical alerts to Slack and email simultaneously\n - Send audit trail events to external webhook endpoints\n - Notify team members via email for object lifecycle events\n - Post cluster completion status to Slack channels\n\nRequirements:\n - Channel type must match the config type (discriminated union)\n - Each config must have valid credentials/endpoints configured\n - Channel configs are validated at webhook creation time","examples":[{"channel":"slack","configs":{"bot_token":"xoxb-...","channel_id":"C0123456789","workspace_id":"T0123456789"},"description":"Slack notification channel"},{"channel":"email","configs":{"recipients":["team@example.com","admin@example.com"],"subject_template":"Mixpeek Alert: {event_type}"},"description":"Email notification channel"},{"channel":"webhook","configs":{"headers":{"Authorization":"Bearer token123"},"method":"POST","url":"https://api.example.com/webhooks/mixpeek"},"description":"HTTP webhook channel"}]},"WebhookConfig":{"properties":{"url":{"type":"string","title":"Url","description":"The URL to which the webhook will be sent."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Custom headers to include in the webhook request."},"payload_template":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Template","description":"A Jinja2 template for the JSON payload."},"timeout":{"type":"number","title":"Timeout","description":"Request timeout in seconds.","default":10.0}},"type":"object","required":["url"],"title":"WebhookConfig","description":"Configuration for webhook notifications."},"WebhookEventType":{"type":"string","enum":["object.created","objects.created.batch","object.updated","object.deleted","collection.created","collection.updated","collection.deleted","collection.documents.written","cluster.created","cluster.updated","cluster.deleted","cluster.execution.started","cluster.execution.completed","cluster.execution.failed","trigger.created","trigger.updated","trigger.deleted","trigger.paused","trigger.resumed","trigger.fired","trigger.execution.completed","trigger.execution.failed","taxonomy.created","taxonomy.updated","taxonomy.deleted","alert.created","alert.updated","alert.deleted","alert.triggered","alert.execution.completed","alert.execution.failed"],"title":"WebhookEventType","description":"Webhook event types for real-time notifications.\n\nThese events are emitted when significant state changes occur in the system.\nWebhooks subscribe to specific event types and receive notifications via\nconfigured channels (email, Slack, HTTP webhooks).\n\nEvent Naming Convention:\n {resource}.{action}[.{sub-resource}[.{sub-action}]]\n\nExamples:\n - object.created: New object ingested\n - collection.documents.written: Documents indexed\n - cluster.execution.completed: Cluster job finished\n\nCache Invalidation Annotations:\n Each event type includes a comment indicating recommended cache invalidation scope:\n - [KEY] = Invalidate specific document/object keys\n - [COLLECTION] = Invalidate collection-level cache\n - [NAMESPACE] = Invalidate namespace-level cache\n\nEvent Categories:\n - Object Lifecycle: Events for individual objects (create, update, delete)\n - Collection Lifecycle: Events for collections (create, update, delete, documents written)\n - Cluster Lifecycle: Events for clusters (create, update, delete, execution status)\n - Trigger Lifecycle: Events for cluster triggers (create, update, fire, execution status)\n - Taxonomy Lifecycle: Events for taxonomies (create, update, delete)\n\nUse Cases:\n - Real-time sync with external systems\n - Audit trail and compliance logging\n - Automated workflows triggered by state changes\n - Cache invalidation for distributed systems\n - Notifications to team members via Slack/email"},"WeightLearningConfig":{"properties":{"method":{"type":"string","enum":["grid_search","bayesian"],"title":"Method","description":"Weight learning method:\n- bayesian: Gaussian process optimization (recommended, scales to 5+ features)\n- grid_search: Exhaustive search (limited to 2-3 features, simpler but slower)","default":"bayesian","examples":["bayesian","grid_search"]},"max_iterations":{"type":"integer","maximum":100.0,"minimum":5.0,"title":"Max Iterations","description":"Maximum optimization iterations:\n- grid_search: Number of values to try per feature (total: max_iterations^n_features)\n- bayesian: Number of weight combinations to evaluate\nRecommended: 20 for bayesian, 5 for grid_search","default":20,"examples":[20,50]},"metric":{"type":"string","enum":["silhouette","davies_bouldin","calinski_harabasz"],"title":"Metric","description":"Clustering quality metric to optimize:\n- silhouette: Measures how similar points are to their cluster vs other clusters (range: [-1, 1], higher is better)\n- davies_bouldin: Ratio of within-cluster to between-cluster distances (range: [0, āˆž], lower is better)\n- calinski_harabasz: Ratio of between-cluster to within-cluster variance (range: [0, āˆž], higher is better)\nRecommended: silhouette (most general-purpose)","default":"silhouette","examples":["silhouette","davies_bouldin","calinski_harabasz"]},"sample_size":{"anyOf":[{"type":"integer","minimum":100.0},{"type":"null"}],"title":"Sample Size","description":"Optional: Learn weights on a random sample (speeds up large datasets).\nIf provided and dataset has more documents, weights are learned on sample_size random documents, then applied to full dataset.\nRecommended: 5000 for datasets >10k documents","examples":[5000,10000]},"random_state":{"type":"integer","title":"Random State","description":"Random seed for reproducibility of weight learning","default":42,"examples":[42]}},"type":"object","title":"WeightLearningConfig","description":"Configuration for automatic feature weight learning in multi-feature clustering.\n\nWhen multi_feature_strategy='weighted' and feature_weights is not provided,\nthis configuration controls how optimal weights are automatically learned.\n\nThe system tries different weight combinations and picks the one that\nproduces the best clustering quality (measured by silhouette score, etc.).\n\nExamples:\n Bayesian optimization (recommended):\n {\n \"method\": \"bayesian\",\n \"max_iterations\": 20,\n \"metric\": \"silhouette\",\n \"sample_size\": 5000\n }\n\n Grid search (exhaustive, limited to 2-3 features):\n {\n \"method\": \"grid_search\",\n \"max_iterations\": 5,\n \"metric\": \"silhouette\"\n }","examples":[{"max_iterations":20,"method":"bayesian","metric":"silhouette","random_state":42,"sample_size":5000},{"max_iterations":5,"method":"grid_search","metric":"silhouette","random_state":42}]},"WriteBackFieldMapping":{"properties":{"source_field":{"type":"string","title":"Source Field","description":"Field path in retriever result (dot notation supported)","examples":["ai_safety_insight.text","category","score"]},"target_field":{"type":"string","title":"Target Field","description":"Field name to write on the document","examples":["_enrichment_category","safety_score","related_items"]},"mode":{"type":"string","enum":["first","all_as_array","concat"],"title":"Mode","description":"How to aggregate values from multiple results. 'first': top result only. 'all_as_array': collect into list. 'concat': join strings with ', '.","default":"first"}},"type":"object","required":["source_field","target_field"],"title":"WriteBackFieldMapping","description":"Maps a field from retriever results back to the document.\n\nControls how retriever result fields are written to the source document.\n\nAttributes:\n source_field: Field path in retriever result (dot notation for nested fields)\n target_field: Field name to write on the document\n mode: How to aggregate values across multiple results:\n - \"first\": Write value from first result only (default)\n - \"all_as_array\": Collect values from all results into a list\n - \"concat\": Concatenate string values with \", \" separator"},"api__analytics__buckets__models__TimeRange":{"properties":{"start":{"type":"string","format":"date-time","title":"Start","description":"Start of time range"},"end":{"type":"string","format":"date-time","title":"End","description":"End of time range"}},"type":"object","required":["start","end"],"title":"TimeRange","description":"Time range for analytics queries."},"api__analytics__clusters__models__FailureAnalysisResponse":{"properties":{"cluster_id":{"type":"string","title":"Cluster Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__clusters__models__TimeRange"},"failures":{"items":{"$ref":"#/components/schemas/FailureMetric"},"type":"array","title":"Failures"},"total_failures":{"type":"integer","title":"Total Failures"}},"type":"object","required":["cluster_id","time_range","failures","total_failures"],"title":"FailureAnalysisResponse","description":"Cluster failure analysis response."},"api__analytics__clusters__models__TimeRange":{"properties":{"start":{"type":"string","format":"date-time","title":"Start"},"end":{"type":"string","format":"date-time","title":"End"}},"type":"object","required":["start","end"],"title":"TimeRange","description":"Time range for analytics queries."},"api__analytics__collections__models__FailureAnalysisResponse":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"time_range":{"$ref":"#/components/schemas/api__analytics__collections__models__TimeRange"},"error_distribution":{"items":{"$ref":"#/components/schemas/ErrorMetrics"},"type":"array","title":"Error Distribution"},"total_errors":{"type":"integer","title":"Total Errors"}},"type":"object","required":["collection_id","time_range","error_distribution","total_errors"],"title":"FailureAnalysisResponse","description":"Failure analysis response."},"api__analytics__collections__models__TimeRange":{"properties":{"start":{"type":"string","format":"date-time","title":"Start"},"end":{"type":"string","format":"date-time","title":"End"}},"type":"object","required":["start","end"],"title":"TimeRange","description":"Time range for analytics queries."},"api__analytics__models__TimeRange":{"properties":{"start":{"type":"string","format":"date-time","title":"Start","description":"Start time (UTC)"},"end":{"type":"string","format":"date-time","title":"End","description":"End time (UTC)"}},"type":"object","required":["start","end"],"title":"TimeRange","description":"Time range for analytics queries."},"api__analytics__taxonomies__models__TimeRange":{"properties":{"start":{"type":"string","format":"date-time","title":"Start"},"end":{"type":"string","format":"date-time","title":"End"}},"type":"object","required":["start","end"],"title":"TimeRange","description":"Time range for analytics queries."},"api__namespaces__plugins__models__CreatePluginUploadRequest":{"properties":{"name":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{2,63}$","title":"Name","description":"Plugin name (alphanumeric with underscores, no spaces)","examples":["sentiment_analyzer","custom_embedder","face_detector"]},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$","title":"Version","description":"Semantic version string. Accepts 'v1', '1.0', '1.0.0' ā€” all normalized to X.Y.Z","examples":["1.0.0","2.1.3","0.0.1"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description of the plugin"},"file_size_bytes":{"anyOf":[{"type":"integer","maximum":524288000.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"File Size Bytes","description":"Expected file size in bytes for quota validation (500MB max)"},"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}},"type":"object","required":["name","version"],"title":"CreatePluginUploadRequest","description":"Request to generate a presigned URL for plugin archive upload.\n\nThis is step 1 of the presigned URL workflow:\n1. POST /namespaces/{id}/plugins/uploads ā†’ Returns presigned_url + upload_id\n2. PUT presigned_url with plugin archive (client uploads directly to S3)\n3. POST /namespaces/{id}/plugins/uploads/{upload_id}/confirm ā†’ Validates and deploys\n\nRequirements:\n - name: Plugin name (e.g., 'my_custom_extractor')\n - version: Semantic version (e.g., '1.0.0')\n - file_size_bytes: Expected archive size for quota validation"},"api__namespaces__plugins__models__PluginDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugin_id":{"type":"string","title":"Plugin Id"},"message":{"type":"string","title":"Message"},"deployment_removed":{"type":"boolean","title":"Deployment Removed","description":"True if a Ray Serve deployment was queued for removal via blue-green deployment","default":false}},"type":"object","required":["plugin_id","message"],"title":"PluginDeleteResponse","description":"Response model for plugin deletion.\n\nIncludes information about Ray Serve deployment removal if the plugin\nwas deployed for realtime inference."},"api__namespaces__plugins__models__PluginDetailResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugin":{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginDocument"},"presigned_download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Presigned Download Url","description":"Presigned URL for downloading the plugin archive (valid for 1 hour)"}},"type":"object","required":["plugin"],"title":"PluginDetailResponse","description":"Response model for plugin details."},"api__namespaces__plugins__models__PluginDocument":{"properties":{"plugin_id":{"type":"string","title":"Plugin Id","description":"Unique plugin identifier"},"namespace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Namespace Id","description":"Owner namespace ID (for namespace-level plugins)"},"organization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Id","description":"Owner organization ID (for org-level plugins)"},"name":{"type":"string","title":"Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version (semver)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Plugin description"},"s3_archive_url":{"type":"string","title":"S3 Archive Url","description":"S3 URL to plugin archive"},"code_hash":{"type":"string","title":"Code Hash","description":"SHA256 hash of plugin code"},"validation_status":{"type":"string","enum":["passed","failed","pending"],"title":"Validation Status","description":"Validation status"},"validation_errors":{"items":{"type":"string"},"type":"array","title":"Validation Errors","description":"Validation error messages"},"security_scan_passed":{"type":"boolean","title":"Security Scan Passed","description":"Whether security scan passed","default":false},"deployed":{"type":"boolean","title":"Deployed","description":"Whether plugin is deployed","default":false},"deployment_info":{"anyOf":[{"$ref":"#/components/schemas/PluginDeploymentInfo"},{"type":"null"}],"description":"Deployment details"},"manifest":{"anyOf":[{"$ref":"#/components/schemas/api__namespaces__plugins__models__PluginManifestMetadata"},{"type":"null"}],"description":"Metadata extracted from manifest.py"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployed At","description":"When plugin was last deployed"},"resolved_inference_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Inference Name","description":"Resolved inference service name (from realtime.py or feature_uri)"}},"type":"object","required":["plugin_id","name","version","s3_archive_url","code_hash","validation_status"],"title":"PluginDocument","description":"Plugin document stored in MongoDB.\n\nSupports both namespace-level and org-level plugins:\n- Namespace plugins have namespace_id\n- Org plugins have organization_id"},"api__namespaces__plugins__models__PluginListResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugins":{"items":{"$ref":"#/components/schemas/PluginListItem"},"type":"array","title":"Plugins"},"total":{"type":"integer","title":"Total"},"namespace_id":{"type":"string","title":"Namespace Id"}},"type":"object","required":["plugins","total","namespace_id"],"title":"PluginListResponse","description":"Response model for listing plugins."},"api__namespaces__plugins__models__PluginManifestMetadata":{"properties":{"feature_extractor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Extractor Name","description":"Plugin name"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Plugin version"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Plugin description"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"Input schema JSON"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"Output schema JSON"},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema","description":"Parameter schema JSON"},"required_vector_indexes":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Required Vector Indexes","description":"Required vector indexes"},"features":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Features","description":"Features defined by the plugin (embeddings, scalars)"},"dependencies":{"items":{"type":"string"},"type":"array","title":"Dependencies","description":"Python package dependencies"},"compute_profile":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Compute Profile","description":"Compute resource requirements for this plugin's pipeline steps. Keys: resource_type (cpu/gpu/api), gpu_memory_gb, actor_memory_gb, batch_size, max_concurrency. Validated into ComputeProfile at pipeline build time."},"serve_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Serve Config","description":"Ray Serve deployment configuration for realtime inference. Keys: num_replicas, min_replicas, max_replicas, target_ongoing_requests, num_cpus, num_gpus, memory_gb. Validated into ServeConfig at deploy time. Takes precedence over compute_profile for Serve resource allocation."},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Feature URI for realtime inference (e.g., mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1)"},"cost_rates":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Cost Rates","description":"Custom credit cost rates for this plugin. When present, the billing system uses these rates instead of ComputeProfile-based pricing. Format: [{\"unit\": \"minute\", \"credits_per_unit\": 50}, ...]. Valid units: minute, image, 1k_tokens, page, face, extraction."}},"type":"object","title":"PluginManifestMetadata","description":"Metadata extracted from plugin manifest.py."},"api__namespaces__plugins__models__PluginPresignedURLResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id","description":"Upload ID to use when confirming"},"presigned_url":{"type":"string","title":"Presigned Url","description":"S3 presigned URL for PUT upload"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key where file will be stored"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the presigned URL expires"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Target namespace"},"name":{"type":"string","title":"Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version"}},"type":"object","required":["upload_id","presigned_url","s3_key","expires_at","namespace_id","name","version"],"title":"PluginPresignedURLResponse","description":"Response containing presigned URL for plugin upload.\n\nAfter receiving this response:\n1. PUT the plugin archive to `presigned_url` with Content-Type: application/gzip\n2. Call POST /namespaces/{id}/plugins/uploads/{upload_id}/confirm to finalize"},"api__plugins__models__CreatePluginUploadRequest":{"properties":{"name":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{2,63}$","title":"Name","description":"Plugin name (alphanumeric with underscores, no spaces)","examples":["sentiment_analyzer","custom_embedder","face_detector"]},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$","title":"Version","description":"Semantic version string","examples":["1.0.0","2.1.3","0.0.1"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description of the plugin"},"file_size_bytes":{"anyOf":[{"type":"integer","maximum":524288000.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"File Size Bytes","description":"Expected file size in bytes for quota validation (500MB max)"},"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}},"type":"object","required":["name","version"],"title":"CreatePluginUploadRequest","description":"Request to generate a presigned URL for plugin archive upload.\n\nThis is step 1 of the presigned URL workflow:\n1. POST /plugins/uploads ā†’ Returns presigned_url + upload_id\n2. PUT presigned_url with plugin archive (client uploads directly to S3)\n3. POST /plugins/uploads/{upload_id}/confirm ā†’ Validates and creates plugin\n\nRequirements:\n - name: Plugin name (e.g., 'my_custom_extractor')\n - version: Semantic version (e.g., '1.0.0')\n - file_size_bytes: Expected archive size for quota validation"},"api__plugins__models__PluginDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugin_id":{"type":"string","title":"Plugin Id"},"message":{"type":"string","title":"Message"}},"type":"object","required":["plugin_id","message"],"title":"PluginDeleteResponse","description":"Response model for plugin deletion."},"api__plugins__models__PluginDetailResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugin":{"$ref":"#/components/schemas/api__plugins__models__PluginDocument"}},"type":"object","required":["plugin"],"title":"PluginDetailResponse","description":"Response model for plugin details."},"api__plugins__models__PluginDocument":{"properties":{"plugin_id":{"type":"string","title":"Plugin Id","description":"Unique plugin identifier"},"organization_id":{"type":"string","title":"Organization Id","description":"Owner organization ID"},"name":{"type":"string","title":"Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version (semver)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Plugin description"},"s3_archive_url":{"type":"string","title":"S3 Archive Url","description":"S3 URL to plugin archive"},"code_hash":{"type":"string","title":"Code Hash","description":"SHA256 hash of plugin code"},"validation_status":{"type":"string","enum":["passed","failed","pending"],"title":"Validation Status","description":"Validation status"},"validation_errors":{"items":{"type":"string"},"type":"array","title":"Validation Errors","description":"Validation error messages"},"security_scan_passed":{"type":"boolean","title":"Security Scan Passed","description":"Whether security scan passed","default":false},"deployed":{"type":"boolean","title":"Deployed","description":"Whether plugin is deployed","default":false},"deployment_info":{"anyOf":[{"$ref":"#/components/schemas/PluginDeploymentInfo"},{"type":"null"}],"description":"Deployment details"},"manifest":{"anyOf":[{"$ref":"#/components/schemas/api__plugins__models__PluginManifestMetadata"},{"type":"null"}],"description":"Metadata extracted from manifest.py"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"deployed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployed At","description":"When plugin was last deployed"},"resolved_inference_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Inference Name","description":"Resolved inference service name (from realtime.py or feature_uri)"}},"type":"object","required":["plugin_id","organization_id","name","version","s3_archive_url","code_hash","validation_status"],"title":"PluginDocument","description":"Plugin document stored in MongoDB.\n\nOrg-scoped: Uses organization_id instead of namespace_id.\nPlugins belong to an organization and can be used by any namespace within that org."},"api__plugins__models__PluginListResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"plugins":{"items":{"$ref":"#/components/schemas/PluginListItem"},"type":"array","title":"Plugins"},"total":{"type":"integer","title":"Total"},"organization_id":{"type":"string","title":"Organization Id"}},"type":"object","required":["plugins","total","organization_id"],"title":"PluginListResponse","description":"Response model for listing plugins."},"api__plugins__models__PluginManifestMetadata":{"properties":{"feature_extractor_name":{"type":"string","title":"Feature Extractor Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Plugin description"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"Input schema JSON"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"Output schema JSON"},"parameter_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameter Schema","description":"Parameter schema JSON"},"required_vector_indexes":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Required Vector Indexes","description":"Required vector indexes"},"features":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Features","description":"Features defined by the plugin (embeddings, scalars)"},"dependencies":{"items":{"type":"string"},"type":"array","title":"Dependencies","description":"Python package dependencies"},"feature_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feature Uri","description":"Feature URI for realtime inference (e.g., mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1)"}},"type":"object","required":["feature_extractor_name","version"],"title":"PluginManifestMetadata","description":"Metadata extracted from plugin manifest.py."},"api__plugins__models__PluginPresignedURLResponse":{"properties":{"upload_id":{"type":"string","title":"Upload Id","description":"Upload ID to use when confirming"},"presigned_url":{"type":"string","title":"Presigned Url","description":"S3 presigned URL for PUT upload"},"s3_key":{"type":"string","title":"S3 Key","description":"S3 object key where file will be stored"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the presigned URL expires"},"organization_id":{"type":"string","title":"Organization Id","description":"Organization ID"},"name":{"type":"string","title":"Name","description":"Plugin name"},"version":{"type":"string","title":"Version","description":"Plugin version"}},"type":"object","required":["upload_id","presigned_url","s3_key","expires_at","organization_id","name","version"],"title":"PluginPresignedURLResponse","description":"Response containing presigned URL for plugin upload.\n\nAfter receiving this response:\n1. PUT the plugin archive to `presigned_url` with Content-Type: application/gzip\n2. Call POST /plugins/uploads/{upload_id}/confirm to finalize"},"shared__clusters__triggers__models__CreateTriggerRequest":{"properties":{"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Id","description":"OPTIONAL. Reference to existing cluster definition. If provided, execution_config is inherited from the cluster. Either cluster_id OR execution_config must be provided.","examples":["cluster_abc123",null]},"execution_config":{"anyOf":[{"$ref":"#/components/schemas/TriggerExecutionConfig"},{"type":"null"}],"description":"OPTIONAL. Clustering configuration for this trigger. Specifies collections and algorithm to use when trigger fires. Required if cluster_id is not provided."},"trigger_type":{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerType","description":"REQUIRED. Type of trigger to create. Determines which schedule_config fields are required. Options: 'cron', 'interval', 'event', 'conditional'."},"schedule_config":{"additionalProperties":true,"type":"object","title":"Schedule Config","description":"REQUIRED. Type-specific schedule configuration. Contents depend on trigger_type. See trigger type examples above for required fields."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"OPTIONAL. Human-readable description of what this trigger does. Helpful for identifying triggers in dashboards.","examples":["Daily clustering at 2am UTC","Re-cluster after 100 documents","Maintain fresh clusters hourly"]},"status":{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerStatus","description":"OPTIONAL. Initial status of trigger. Defaults to 'active' (enabled). Can be set to 'paused' to create disabled trigger.","default":"active"}},"type":"object","required":["trigger_type","schedule_config"],"title":"CreateTriggerRequest","description":"Request to create a new cluster trigger.\n\nCreates an automated trigger that executes clustering based on schedules, events, or conditions.\n\nRequirements:\n - trigger_type: REQUIRED - Determines which schedule_config fields are needed\n - schedule_config: REQUIRED - Configuration specific to trigger_type\n - execution_config OR cluster_id: REQUIRED - Either provide config directly or reference existing cluster\n\nTrigger Types and schedule_config:\n - **cron**: Requires {\"cron_expression\": str, \"timezone\": str}\n - **interval**: Requires {\"interval_seconds\": int, \"start_immediately\": bool}\n - **event**: Requires {\"event_type\": str, \"event_threshold\": int, \"collection_id\": str, \"cooldown_seconds\": int}\n - **conditional**: Requires {\"condition_type\": str, \"threshold\": float, \"metric\": str, \"check_interval_seconds\": int}\n\nUse Cases:\n - Scheduled maintenance: Use cron or interval triggers\n - Reactive clustering: Use event triggers to cluster when data changes\n - Intelligent clustering: Use conditional triggers based on metrics\n\nExamples:\n Cron trigger (daily at 2am UTC):\n {\n \"trigger_type\": \"cron\",\n \"schedule_config\": {\n \"cron_expression\": \"0 2 * * *\",\n \"timezone\": \"UTC\"\n },\n \"execution_config\": {\n \"collection_ids\": [\"col_abc123\"],\n \"config\": {\n \"algorithm\": \"kmeans\",\n \"n_clusters\": 5\n }\n },\n \"description\": \"Daily clustering at 2am\"\n }\n\n Interval trigger (every 6 hours):\n {\n \"trigger_type\": \"interval\",\n \"schedule_config\": {\n \"interval_seconds\": 21600,\n \"start_immediately\": false\n },\n \"execution_config\": {\n \"collection_ids\": [\"col_products\"],\n \"config\": {\n \"algorithm\": \"hdbscan\",\n \"min_cluster_size\": 10\n }\n },\n \"description\": \"Cluster every 6 hours\"\n }\n\n Event trigger (after 100 documents added):\n {\n \"trigger_type\": \"event\",\n \"schedule_config\": {\n \"event_type\": \"documents_added\",\n \"event_threshold\": 100,\n \"collection_id\": \"col_abc123\",\n \"cooldown_seconds\": 300\n },\n \"execution_config\": {\n \"collection_ids\": [\"col_abc123\"],\n \"config\": {\n \"algorithm\": \"kmeans\",\n \"n_clusters\": 3\n }\n },\n \"description\": \"Cluster after 100 new documents\"\n }\n\n Conditional trigger (when drift exceeds 30%):\n {\n \"trigger_type\": \"conditional\",\n \"schedule_config\": {\n \"condition_type\": \"drift\",\n \"threshold\": 0.3,\n \"metric\": \"cosine_drift\",\n \"check_interval_seconds\": 3600\n },\n \"execution_config\": {\n \"collection_ids\": [\"col_abc123\"],\n \"config\": {\n \"algorithm\": \"hdbscan\",\n \"min_cluster_size\": 5\n }\n },\n \"description\": \"Re-cluster when drift > 30%\"\n }\n\n Using existing cluster definition:\n {\n \"trigger_type\": \"interval\",\n \"schedule_config\": {\n \"interval_seconds\": 3600,\n \"start_immediately\": true\n },\n \"cluster_id\": \"cluster_xyz789\",\n \"description\": \"Hourly clustering using cluster_xyz789\"\n }","examples":[{"description":"Daily clustering at 2am UTC","execution_config":{"collection_ids":["col_abc123"],"config":{"algorithm":"kmeans","min_cluster_size":2,"n_clusters":5}},"schedule_config":{"cron_expression":"0 2 * * *","timezone":"UTC"},"trigger_type":"cron"},{"description":"Cluster every 6 hours","execution_config":{"collection_ids":["col_products"],"config":{"algorithm":"hdbscan","min_cluster_size":10,"min_samples":5}},"schedule_config":{"interval_seconds":21600,"start_immediately":false},"trigger_type":"interval"},{"description":"Cluster after 100 new documents","execution_config":{"collection_ids":["col_abc123"],"config":{"algorithm":"kmeans","n_clusters":3}},"schedule_config":{"collection_id":"col_abc123","cooldown_seconds":300,"event_threshold":100,"event_type":"documents_added"},"trigger_type":"event"},{"description":"Re-cluster when drift > 30%","execution_config":{"collection_ids":["col_abc123"],"config":{"algorithm":"hdbscan","min_cluster_size":5}},"schedule_config":{"check_interval_seconds":3600,"condition_type":"drift","metric":"cosine_drift","threshold":0.3},"trigger_type":"conditional"},{"cluster_id":"cluster_xyz789","description":"Hourly clustering using cluster_xyz789","schedule_config":{"interval_seconds":3600,"start_immediately":true},"trigger_type":"interval"}]},"shared__clusters__triggers__models__ListTriggersRequest":{"properties":{"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Id","description":"Filter by cluster ID"},"trigger_type":{"anyOf":[{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerType"},{"type":"null"}],"description":"Filter by trigger type"},"status":{"anyOf":[{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerStatus"},{"type":"null"}],"description":"Filter by status"},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Pagination offset","default":0},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Results per page","default":50},"sort_by":{"type":"string","title":"Sort By","description":"Field to sort by","default":"created_at"},"direction":{"type":"string","title":"Direction","description":"Sort direction (asc/desc)","default":"desc"}},"type":"object","title":"ListTriggersRequest","description":"Request to list triggers with filters and pagination."},"shared__clusters__triggers__models__ListTriggersResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerModel"},"type":"array","title":"Results","description":"List of triggers"},"total":{"type":"integer","title":"Total","description":"Total number of triggers"},"offset":{"type":"integer","title":"Offset","description":"Current offset"},"limit":{"type":"integer","title":"Limit","description":"Current limit"}},"type":"object","required":["results","total","offset","limit"],"title":"ListTriggersResponse","description":"Response for list triggers request."},"shared__clusters__triggers__models__TriggerHistoryResponse":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id","description":"Trigger ID"},"executions":{"items":{"$ref":"#/components/schemas/TriggerExecutionHistoryItem"},"type":"array","title":"Executions","description":"Execution history"},"total":{"type":"integer","title":"Total","description":"Total executions"},"offset":{"type":"integer","title":"Offset","description":"Current offset"},"limit":{"type":"integer","title":"Limit","description":"Current limit"}},"type":"object","required":["trigger_id","executions","total","offset","limit"],"title":"TriggerHistoryResponse","description":"Response for trigger execution history."},"shared__clusters__triggers__models__TriggerModel":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id","description":"Unique trigger ID"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Id","description":"Optional link to cluster definition"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal ID"},"execution_config":{"$ref":"#/components/schemas/TriggerExecutionConfig","description":"Configuration for cluster execution"},"trigger_type":{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerType","description":"Type of trigger"},"schedule_config":{"additionalProperties":true,"type":"object","title":"Schedule Config","description":"Type-specific schedule configuration"},"status":{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerStatus","description":"Current status","default":"active"},"last_triggered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Triggered At","description":"Last time trigger fired"},"last_execution_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Job Id","description":"Job ID of last execution"},"next_scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Scheduled At","description":"Next scheduled execution time"},"execution_count":{"type":"integer","title":"Execution Count","description":"Total executions","default":0},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Consecutive execution failures","default":0},"last_execution_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Status","description":"Status of last execution"},"last_execution_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Error","description":"Error from last execution"},"event_counter":{"type":"integer","title":"Event Counter","description":"Current event count since last trigger","default":0},"last_cooldown_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Cooldown At","description":"Last time cooldown was applied"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"User who created trigger"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Trigger description"}},"type":"object","required":["namespace_id","internal_id","execution_config","trigger_type","schedule_config"],"title":"TriggerModel","description":"Model for cluster trigger."},"shared__clusters__triggers__models__TriggerStatus":{"type":"string","enum":["active","paused","disabled","failed"],"title":"TriggerStatus","description":"Status of a cluster trigger."},"shared__clusters__triggers__models__TriggerType":{"type":"string","enum":["cron","interval","event","conditional"],"title":"TriggerType","description":"Type of trigger for automated cluster execution.\n\nSupported trigger types:\n- **cron**: Schedule-based execution using cron expressions (e.g., daily at 2am)\n- **interval**: Fixed-interval execution (e.g., every 6 hours)\n- **event**: Event-driven execution (e.g., after 100 documents added)\n- **conditional**: Condition-based execution (e.g., when drift exceeds threshold)"},"shared__clusters__triggers__models__UpdateTriggerRequest":{"properties":{"schedule_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Schedule Config","description":"Updated schedule configuration"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated description"},"status":{"anyOf":[{"$ref":"#/components/schemas/shared__clusters__triggers__models__TriggerStatus"},{"type":"null"}],"description":"Updated status"}},"type":"object","title":"UpdateTriggerRequest","description":"Request to update an existing trigger."},"shared__collection__features__extractors__models__FeatureExtractorConfig-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'}"},"parameters":{"anyOf":[{"$ref":"#/components/schemas/TextExtractorParams"},{"$ref":"#/components/schemas/MultimodalExtractorParams"},{"$ref":"#/components/schemas/FaceIdentityExtractorParams"},{"$ref":"#/components/schemas/ImageExtractorParams"},{"$ref":"#/components/schemas/DocumentGraphExtractorParams"},{"$ref":"#/components/schemas/SentimentClassifierParams"},{"$ref":"#/components/schemas/WebScraperExtractorParams"},{"$ref":"#/components/schemas/CourseContentExtractorParams"},{"$ref":"#/components/schemas/CustomPluginParams"},{"type":"null"}],"title":"Parameters","description":"Parameters for the feature extractor. Each extractor type has specific parameters. See the schema for your chosen extractor (e.g., MultimodalExtractorParams for multimodal_extractor).","examples":[{"split_method":"time","time_split_interval":10},{"chunk_size":512,"split_by":"sentences"}]},"input_mappings":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"}],"title":"Input Mappings","description":"Mapping from extractor input names to source field paths. Tells the extractor which source fields to process. Example: {'image': 'thumbnail_url', 'text': 'description'}","examples":[{"image":"product_image","text":"title"},{"video":"video_url"},{"text":"content"}]},"field_passthrough":{"items":{"$ref":"#/components/schemas/FieldPassthrough"},"type":"array","title":"Field Passthrough","description":"NOT REQUIRED. List of specific fields to pass through from source to output documents. These fields are included alongside extractor-computed features (embeddings, detections, etc.). Empty list = only extractor outputs in documents (default behavior). With entries = specified fields + extractor outputs in documents. \n\nHow It Works:\n1. During processing, fields are extracted from source object/document\n2. They appear in output documents at the root level\n3. Field filtering happens automatically (only listed fields included)\n4. Use target_path to rename fields for cleaner schemas\n\nCommon Use Cases:\n- Preserve identifiers: campaign_id, product_sku, order_id\n- Keep metadata: category, tags, author, created_at\n- Enable filtering: department, status, priority, region\n- Maintain context: title, description, source_url\n\nBehavior:\n- Works with include_all_source_fields=False (default): ONLY these fields included\n- Works with include_all_source_fields=True: These configs used for renaming/defaults\n- Fields must exist in source bucket_schema or upstream collection output_schema\n- Missing optional fields are omitted (unless default provided)\n- Missing required fields cause processing errors\n\nOutput Schema:\noutput_schema = field_passthrough fields + extractor output fields\nExample: ['title', 'category', 'text_extractor_v1_embedding']","examples":[[{"required":true,"source_path":"title"},{"required":true,"source_path":"campaign_id"}],[{"default":"uncategorized","source_path":"category"},{"source_path":"metadata.author","target_path":"author"}]]},"include_all_source_fields":{"type":"boolean","title":"Include All Source Fields","description":"NOT REQUIRED. Whether to include ALL fields from source object/document in output. Default: False (only field_passthrough fields included). \n\nWhen False (RECOMMENDED):\n- Only fields listed in field_passthrough are included in output\n- Creates clean, predictable output schemas\n- Prevents data leakage of unwanted fields\n- Output = field_passthrough fields + extractor outputs\n\nWhen True (USE WITH CAUTION):\n- ALL source fields are included in output documents\n- field_passthrough still used for renaming/defaults/requirements\n- Can result in large documents if source has many fields\n- Can leak sensitive or unnecessary data\n- Output = all source fields + extractor outputs\n\nUse True When:\n- You want to preserve complete source data\n- Source has limited, well-defined fields\n- Downstream processing needs all context\n\nUse False When (MOST CASES):\n- You want clean, controlled output schemas\n- Source has many fields you don't need\n- You want explicit field selection\n- You're concerned about document size\n\nExamples:\nFalse: source={a,b,c,d} + passthrough=[a,b] ā†’ output={a,b,embedding}\nTrue: source={a,b,c,d} + passthrough=[aā†’x] ā†’ output={x,b,c,d,embedding}","default":false}},"additionalProperties":false,"type":"object","required":["feature_extractor_name","version"],"title":"FeatureExtractorConfig","description":"Configuration for a feature extractor with field passthrough support.\n\nA feature extractor processes source data (from buckets or collections) and\nproduces features (embeddings, extracted text, detected objects, etc.).\n\nWith field passthrough, you can also include selected source fields in the\noutput documents alongside the computed features.\n\nCore Concepts:\n 1. **Feature Extraction**: Extractors compute features from input data\n (e.g., text ā†’ embeddings, image ā†’ detections, video ā†’ scenes)\n 2. **Field Passthrough**: Selectively preserve source fields in output\n (e.g., title, category, campaign_id from source ā†’ output documents)\n 3. **Output Schema**: Combination of passed-through fields + extractor outputs\n (e.g., {title, category, text_embedding} all in one document)\n\nHow Field Passthrough Works:\n 1. Define which source fields to include via field_passthrough list\n 2. During processing, these fields are extracted from source\n 3. They appear in output documents at root level\n 4. Combine with extractor outputs for complete documents\n 5. Use target_path to rename fields for cleaner schemas\n\nField Selection Modes:\n - **Explicit** (field_passthrough + include_all=False):\n Only listed fields pass through. Clean, controlled output.\n Example: passthrough=[title, category] ā†’ output has ONLY title, category, embedding\n\n - **Inclusive** (include_all=True):\n All source fields pass through, field_passthrough for renaming.\n Example: source has 10 fields ā†’ output has all 10 + embedding\n\n - **None** (no field_passthrough):\n Only extractor outputs in documents.\n Example: ā†’ output has ONLY embedding (no source fields)\n\nUse Cases:\n - **Preserve Identifiers**: Keep campaign_id, product_sku, order_id for tracking\n - **Enable Filtering**: Pass category, status, department for query filters\n - **Maintain Context**: Include title, description for display\n - **Track Metadata**: Preserve author, created_at, source for lineage\n - **Business Logic**: Keep priority, region, type for application logic\n\nCommon Patterns:\n 1. **Minimal Passthrough** (recommended):\n field_passthrough=[{\"source_path\": \"id\"}], include_all=False\n ā†’ Clean output, only ID + extractor features\n\n 2. **Metadata Preservation**:\n field_passthrough=[\n {\"source_path\": \"title\"},\n {\"source_path\": \"category\"},\n {\"source_path\": \"created_at\"}\n ]\n ā†’ Document has context for display and filtering\n\n 3. **Field Renaming**:\n field_passthrough=[\n {\"source_path\": \"doc_title\", \"target_path\": \"title\"},\n {\"source_path\": \"metadata.author\", \"target_path\": \"author\"}\n ]\n ā†’ Cleaner output schema with flattened fields\n\n 4. **Required Fields**:\n field_passthrough=[\n {\"source_path\": \"campaign_id\", \"required\": True},\n {\"source_path\": \"priority\", \"default\": 0}\n ]\n ā†’ Ensures critical fields always present\n\nRequirements:\n - feature_extractor_name: REQUIRED - name of the extractor\n - version: REQUIRED - extractor version (e.g., \"v1\")\n - parameters: NOT REQUIRED - extractor-specific config (model, thresholds, etc.)\n - input_mappings: NOT REQUIRED - maps extractor inputs to source fields\n - field_passthrough: NOT REQUIRED - which source fields to preserve (default: none)\n - include_all_source_fields: NOT REQUIRED - preserve all fields (default: false)","examples":[{"description":"Text extractor with field passthrough","feature_extractor_name":"text_extractor","field_passthrough":[{"required":true,"source_path":"title"},{"source_path":"author"}],"input_mappings":{"text":"content"},"parameters":{"model":"text-embedding-3-small"},"version":"v1"},{"description":"Video extractor with campaign metadata","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"},{"description":"Image extractor with all source fields","feature_extractor_name":"image_extractor","include_all_source_fields":true,"input_mappings":{"image":"product_image"},"parameters":{"model":"clip-vit-base-patch32"},"version":"v1"},{"description":"Text extractor with field renaming","feature_extractor_name":"text_extractor","field_passthrough":[{"source_path":"metadata.author","target_path":"author"},{"source_path":"metadata.created_at","target_path":"created_at"}],"input_mappings":{"text":"content"},"version":"v1"}]},"shared__collection__features__extractors__models__FeatureExtractorConfig-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'}"},"parameters":{"anyOf":[{"$ref":"#/components/schemas/TextExtractorParams"},{"$ref":"#/components/schemas/MultimodalExtractorParams"},{"$ref":"#/components/schemas/FaceIdentityExtractorParams"},{"$ref":"#/components/schemas/ImageExtractorParams"},{"$ref":"#/components/schemas/DocumentGraphExtractorParams"},{"$ref":"#/components/schemas/SentimentClassifierParams"},{"$ref":"#/components/schemas/WebScraperExtractorParams"},{"$ref":"#/components/schemas/CourseContentExtractorParams"},{"$ref":"#/components/schemas/CustomPluginParams"},{"type":"null"}],"title":"Parameters","description":"Parameters for the feature extractor. Each extractor type has specific parameters. See the schema for your chosen extractor (e.g., MultimodalExtractorParams for multimodal_extractor).","examples":[{"split_method":"time","time_split_interval":10},{"chunk_size":512,"split_by":"sentences"}]},"input_mappings":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"items":{"$ref":"#/components/schemas/InputMapping"},"type":"array"}],"title":"Input Mappings","description":"Mapping from extractor input names to source field paths. Tells the extractor which source fields to process. Example: {'image': 'thumbnail_url', 'text': 'description'}","examples":[{"image":"product_image","text":"title"},{"video":"video_url"},{"text":"content"}]},"field_passthrough":{"items":{"$ref":"#/components/schemas/FieldPassthrough"},"type":"array","title":"Field Passthrough","description":"NOT REQUIRED. List of specific fields to pass through from source to output documents. These fields are included alongside extractor-computed features (embeddings, detections, etc.). Empty list = only extractor outputs in documents (default behavior). With entries = specified fields + extractor outputs in documents. \n\nHow It Works:\n1. During processing, fields are extracted from source object/document\n2. They appear in output documents at the root level\n3. Field filtering happens automatically (only listed fields included)\n4. Use target_path to rename fields for cleaner schemas\n\nCommon Use Cases:\n- Preserve identifiers: campaign_id, product_sku, order_id\n- Keep metadata: category, tags, author, created_at\n- Enable filtering: department, status, priority, region\n- Maintain context: title, description, source_url\n\nBehavior:\n- Works with include_all_source_fields=False (default): ONLY these fields included\n- Works with include_all_source_fields=True: These configs used for renaming/defaults\n- Fields must exist in source bucket_schema or upstream collection output_schema\n- Missing optional fields are omitted (unless default provided)\n- Missing required fields cause processing errors\n\nOutput Schema:\noutput_schema = field_passthrough fields + extractor output fields\nExample: ['title', 'category', 'text_extractor_v1_embedding']","examples":[[{"required":true,"source_path":"title"},{"required":true,"source_path":"campaign_id"}],[{"default":"uncategorized","source_path":"category"},{"source_path":"metadata.author","target_path":"author"}]]},"include_all_source_fields":{"type":"boolean","title":"Include All Source Fields","description":"NOT REQUIRED. Whether to include ALL fields from source object/document in output. Default: False (only field_passthrough fields included). \n\nWhen False (RECOMMENDED):\n- Only fields listed in field_passthrough are included in output\n- Creates clean, predictable output schemas\n- Prevents data leakage of unwanted fields\n- Output = field_passthrough fields + extractor outputs\n\nWhen True (USE WITH CAUTION):\n- ALL source fields are included in output documents\n- field_passthrough still used for renaming/defaults/requirements\n- Can result in large documents if source has many fields\n- Can leak sensitive or unnecessary data\n- Output = all source fields + extractor outputs\n\nUse True When:\n- You want to preserve complete source data\n- Source has limited, well-defined fields\n- Downstream processing needs all context\n\nUse False When (MOST CASES):\n- You want clean, controlled output schemas\n- Source has many fields you don't need\n- You want explicit field selection\n- You're concerned about document size\n\nExamples:\nFalse: source={a,b,c,d} + passthrough=[a,b] ā†’ output={a,b,embedding}\nTrue: source={a,b,c,d} + passthrough=[aā†’x] ā†’ output={x,b,c,d,embedding}","default":false},"feature_extractor_id":{"type":"string","title":"Feature Extractor Id","description":"Construct unique identifier for the feature extractor instance (name + version).","readOnly":true}},"additionalProperties":false,"type":"object","required":["feature_extractor_name","version","feature_extractor_id"],"title":"FeatureExtractorConfig","description":"Configuration for a feature extractor with field passthrough support.\n\nA feature extractor processes source data (from buckets or collections) and\nproduces features (embeddings, extracted text, detected objects, etc.).\n\nWith field passthrough, you can also include selected source fields in the\noutput documents alongside the computed features.\n\nCore Concepts:\n 1. **Feature Extraction**: Extractors compute features from input data\n (e.g., text ā†’ embeddings, image ā†’ detections, video ā†’ scenes)\n 2. **Field Passthrough**: Selectively preserve source fields in output\n (e.g., title, category, campaign_id from source ā†’ output documents)\n 3. **Output Schema**: Combination of passed-through fields + extractor outputs\n (e.g., {title, category, text_embedding} all in one document)\n\nHow Field Passthrough Works:\n 1. Define which source fields to include via field_passthrough list\n 2. During processing, these fields are extracted from source\n 3. They appear in output documents at root level\n 4. Combine with extractor outputs for complete documents\n 5. Use target_path to rename fields for cleaner schemas\n\nField Selection Modes:\n - **Explicit** (field_passthrough + include_all=False):\n Only listed fields pass through. Clean, controlled output.\n Example: passthrough=[title, category] ā†’ output has ONLY title, category, embedding\n\n - **Inclusive** (include_all=True):\n All source fields pass through, field_passthrough for renaming.\n Example: source has 10 fields ā†’ output has all 10 + embedding\n\n - **None** (no field_passthrough):\n Only extractor outputs in documents.\n Example: ā†’ output has ONLY embedding (no source fields)\n\nUse Cases:\n - **Preserve Identifiers**: Keep campaign_id, product_sku, order_id for tracking\n - **Enable Filtering**: Pass category, status, department for query filters\n - **Maintain Context**: Include title, description for display\n - **Track Metadata**: Preserve author, created_at, source for lineage\n - **Business Logic**: Keep priority, region, type for application logic\n\nCommon Patterns:\n 1. **Minimal Passthrough** (recommended):\n field_passthrough=[{\"source_path\": \"id\"}], include_all=False\n ā†’ Clean output, only ID + extractor features\n\n 2. **Metadata Preservation**:\n field_passthrough=[\n {\"source_path\": \"title\"},\n {\"source_path\": \"category\"},\n {\"source_path\": \"created_at\"}\n ]\n ā†’ Document has context for display and filtering\n\n 3. **Field Renaming**:\n field_passthrough=[\n {\"source_path\": \"doc_title\", \"target_path\": \"title\"},\n {\"source_path\": \"metadata.author\", \"target_path\": \"author\"}\n ]\n ā†’ Cleaner output schema with flattened fields\n\n 4. **Required Fields**:\n field_passthrough=[\n {\"source_path\": \"campaign_id\", \"required\": True},\n {\"source_path\": \"priority\", \"default\": 0}\n ]\n ā†’ Ensures critical fields always present\n\nRequirements:\n - feature_extractor_name: REQUIRED - name of the extractor\n - version: REQUIRED - extractor version (e.g., \"v1\")\n - parameters: NOT REQUIRED - extractor-specific config (model, thresholds, etc.)\n - input_mappings: NOT REQUIRED - maps extractor inputs to source fields\n - field_passthrough: NOT REQUIRED - which source fields to preserve (default: none)\n - include_all_source_fields: NOT REQUIRED - preserve all fields (default: false)","examples":[{"description":"Text extractor with field passthrough","feature_extractor_name":"text_extractor","field_passthrough":[{"required":true,"source_path":"title"},{"source_path":"author"}],"input_mappings":{"text":"content"},"parameters":{"model":"text-embedding-3-small"},"version":"v1"},{"description":"Video extractor with campaign metadata","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"},{"description":"Image extractor with all source fields","feature_extractor_name":"image_extractor","include_all_source_fields":true,"input_mappings":{"image":"product_image"},"parameters":{"model":"clip-vit-base-patch32"},"version":"v1"},{"description":"Text extractor with field renaming","feature_extractor_name":"text_extractor","field_passthrough":[{"source_path":"metadata.author","target_path":"author"},{"source_path":"metadata.created_at","target_path":"created_at"}],"input_mappings":{"text":"content"},"version":"v1"}]},"shared__namespaces__migrations__models__FeatureExtractorConfig":{"properties":{"feature_extractor_name":{"type":"string","title":"Feature Extractor Name","description":"Name of the extractor"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Version to use"},"parameters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parameters","description":"Extractor parameters"}},"type":"object","required":["feature_extractor_name"],"title":"FeatureExtractorConfig","description":"Configuration for a feature extractor in migration."},"shared__namespaces__migrations__models__ResourceType":{"type":"string","enum":["bucket","collection","taxonomy","cluster","retriever"],"title":"ResourceType","description":"Types of resources that can be migrated."},"shared__organizations__enums__ResourceType":{"type":"string","enum":["organization","user","api_key","namespace","collection","bucket","retriever","cluster","taxonomy","storage_connection","alert"],"title":"ResourceType","description":"Resource surfaces supported by scoped API keys and audit events.\n\nThese resource types can be used in:\n- API key scopes to restrict access to specific resources\n- Audit logs to identify what type of resource was affected\n- Permission systems to grant/deny access to resource categories\n\nResource hierarchy:\n ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION\n NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY\n\nResource types:\n - ORGANIZATION: Top-level tenant entity\n - USER: Organization member with authentication credentials\n - API_KEY: Authentication token for programmatic access\n - NAMESPACE: Isolated environment for data and compute resources\n - COLLECTION: Vector database collection for searchable documents\n - BUCKET: Object storage container for raw files\n - RETRIEVER: Configured search/retrieval pipeline\n - CLUSTER: Ray compute cluster for distributed processing\n - TAXONOMY: Hierarchical classification system for documents\n - STORAGE_CONNECTION: External storage provider integration"},"shared__retrievers__benchmarks__models__TimeRange":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start","description":"Start of time range (inclusive)."},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End","description":"End of time range (inclusive)."}},"type":"object","title":"TimeRange","description":"Time range filter for session queries."},"shared__triggers__models__CreateTriggerRequest":{"properties":{"action_type":{"$ref":"#/components/schemas/TriggerActionType","description":"Type of action to execute"},"action_config":{"additionalProperties":true,"type":"object","title":"Action Config","description":"Action-specific configuration"},"trigger_type":{"$ref":"#/components/schemas/shared__triggers__models__TriggerType","description":"Type of schedule"},"schedule_config":{"additionalProperties":true,"type":"object","title":"Schedule Config","description":"Schedule-specific configuration"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"status":{"$ref":"#/components/schemas/shared__triggers__models__TriggerStatus","description":"Initial status (active or paused)","default":"active"}},"type":"object","required":["action_type","action_config","trigger_type","schedule_config"],"title":"CreateTriggerRequest","description":"Request to create a new trigger.\n\nExamples:\n Cluster trigger (cron):\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 Taxonomy trigger (interval):\n {\n \"action_type\": \"taxonomy_enrichment\",\n \"action_config\": {\"taxonomy_id\": \"tax_products\", \"collection_id\": \"col_inv\"},\n \"trigger_type\": \"interval\",\n \"schedule_config\": {\"interval_seconds\": 21600},\n \"description\": \"Re-enrich every 6 hours\"\n }","examples":[{"action_config":{"cluster_id":"clust_abc123"},"action_type":"cluster","description":"Daily clustering at 2am","schedule_config":{"cron_expression":"0 2 * * *","timezone":"UTC"},"trigger_type":"cron"},{"action_config":{"cluster_id":"clust_abc123","filters":{"status":"active"},"output_collection_ids":["col_daily_clusters"]},"action_type":"cluster","description":"Daily clustering of active items with output override","schedule_config":{"cron_expression":"0 2 * * *","timezone":"UTC"},"trigger_type":"cron"},{"action_config":{"collection_id":"col_inventory","taxonomy_id":"tax_products"},"action_type":"taxonomy_enrichment","description":"Re-enrich products every 6 hours (in-place)","schedule_config":{"interval_seconds":21600,"start_immediately":false},"trigger_type":"interval"},{"action_config":{"collection_id":"col_inventory","incremental":true,"taxonomy_id":"tax_products"},"action_type":"taxonomy_enrichment","description":"Hourly incremental enrichment (only new docs)","schedule_config":{"interval_seconds":3600},"trigger_type":"interval"},{"action_config":{"batch_size":500,"collection_id":"col_inventory","incremental":true,"parallelism":8,"target_collection_id":"col_enriched","taxonomy_id":"tax_products"},"action_type":"taxonomy_enrichment","description":"Nightly incremental enrichment to target collection","schedule_config":{"cron_expression":"0 3 * * *","timezone":"UTC"},"trigger_type":"cron"}]},"shared__triggers__models__ListTriggersRequest":{"properties":{"action_type":{"anyOf":[{"$ref":"#/components/schemas/TriggerActionType"},{"type":"null"}],"description":"Filter by action type"},"trigger_type":{"anyOf":[{"$ref":"#/components/schemas/shared__triggers__models__TriggerType"},{"type":"null"}],"description":"Filter by trigger type"},"status":{"anyOf":[{"$ref":"#/components/schemas/shared__triggers__models__TriggerStatus"},{"type":"null"}],"description":"Filter by status"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"Filter by resource ID (cluster_id or taxonomy_id)"},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Pagination offset","default":0},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Results per page","default":50},"sort_by":{"type":"string","title":"Sort By","description":"Field to sort by","default":"created_at"},"direction":{"type":"string","title":"Direction","description":"Sort direction (asc/desc)","default":"desc"}},"type":"object","title":"ListTriggersRequest","description":"Request to list triggers with filters."},"shared__triggers__models__ListTriggersResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/shared__triggers__models__TriggerModel"},"type":"array","title":"Results","description":"List of triggers"},"total":{"type":"integer","title":"Total","description":"Total number of triggers"},"offset":{"type":"integer","title":"Offset","description":"Current offset"},"limit":{"type":"integer","title":"Limit","description":"Current limit"}},"type":"object","required":["results","total","offset","limit"],"title":"ListTriggersResponse","description":"Response for list triggers request."},"shared__triggers__models__TriggerHistoryResponse":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id","description":"Trigger ID"},"executions":{"items":{"$ref":"#/components/schemas/TriggerExecutionHistory"},"type":"array","title":"Executions","description":"Execution history"},"total":{"type":"integer","title":"Total","description":"Total executions"},"offset":{"type":"integer","title":"Offset","description":"Current offset"},"limit":{"type":"integer","title":"Limit","description":"Current limit"}},"type":"object","required":["trigger_id","executions","total","offset","limit"],"title":"TriggerHistoryResponse","description":"Response for trigger execution history."},"shared__triggers__models__TriggerModel":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id","description":"Unique trigger identifier"},"namespace_id":{"type":"string","title":"Namespace Id","description":"Namespace ID"},"internal_id":{"type":"string","title":"Internal Id","description":"Organization internal ID"},"action_type":{"$ref":"#/components/schemas/TriggerActionType","description":"Type of action to execute"},"action_config":{"additionalProperties":true,"type":"object","title":"Action Config","description":"Action-specific configuration"},"trigger_type":{"$ref":"#/components/schemas/shared__triggers__models__TriggerType","description":"Type of schedule"},"schedule_config":{"additionalProperties":true,"type":"object","title":"Schedule Config","description":"Schedule-specific configuration"},"status":{"$ref":"#/components/schemas/shared__triggers__models__TriggerStatus","description":"Current trigger status","default":"active"},"last_triggered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Triggered At","description":"Last time trigger fired"},"last_execution_task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Task Id","description":"Task ID of last execution"},"next_scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Scheduled At","description":"Next scheduled execution time"},"execution_count":{"type":"integer","title":"Execution Count","description":"Total successful executions","default":0},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Consecutive failures","default":0},"last_execution_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Status","description":"Status of last execution"},"last_execution_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Execution Error","description":"Error from last execution (if failed)"},"event_counter":{"type":"integer","title":"Event Counter","description":"Current event count since last trigger","default":0},"last_cooldown_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Cooldown At","description":"Last time cooldown was applied"},"baseline_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Baseline Snapshot","description":"Baseline snapshot for drift measurement (captured after successful execution)"},"last_drift_measurement":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Last Drift Measurement","description":"Result of most recent drift measurement check"},"last_condition_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Condition Check At","description":"When condition was last evaluated"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"User who created trigger"}},"type":"object","required":["namespace_id","internal_id","action_type","action_config","trigger_type","schedule_config"],"title":"TriggerModel","description":"Unified trigger model for all action types.\n\nA trigger defines:\n1. **What** to execute (action_type + action_config)\n2. **When** to execute (trigger_type + schedule_config)\n3. **State** tracking (execution count, failures, next scheduled time)"},"shared__triggers__models__TriggerStatus":{"type":"string","enum":["active","paused","disabled","failed"],"title":"TriggerStatus","description":"Status of a trigger."},"shared__triggers__models__TriggerType":{"type":"string","enum":["cron","interval","event","conditional"],"title":"TriggerType","description":"Type of trigger schedule.\n\nSupported trigger types:\n- **cron**: Schedule-based execution using cron expressions\n- **interval**: Fixed-interval execution\n- **event**: Event-driven execution\n- **conditional**: Condition-based execution"},"shared__triggers__models__UpdateTriggerRequest":{"properties":{"schedule_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Schedule Config","description":"Updated schedule configuration"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Updated description"},"status":{"anyOf":[{"$ref":"#/components/schemas/shared__triggers__models__TriggerStatus"},{"type":"null"}],"description":"Updated status"}},"type":"object","title":"UpdateTriggerRequest","description":"Request to update an existing trigger.\n\nOnly provided fields will be updated."}}}}