{"openapi":"3.0.3","info":{"title":"ASK Public API Layer","description":"This API reference describes the RESTful, streaming, and realtime APIs you can use to interact with the ASK platform. REST APIs are usable via HTTP in any environment that supports HTTP requests.\n\n### Rate Limiting\nAll `/v1` endpoints use a Redis-backed sliding window (60 seconds) rate limiter. Requests are keyed by `X-API-Key` when present, otherwise by the caller's IP address. API keys inherit limits from their assigned tier and are cached in Redis to avoid repeated lookups. Each response may include:\n- `X-RateLimit-Limit`: maximum responses allowed in the current 60-second window.\n- `X-RateLimit-Remaining`: remaining responses in the active window.\n- `X-RateLimit-Reset`: ISO-8601 timestamp indicating when the next window begins.\nWhen the limit is exceeded, the API responds with HTTP 429 and a JSON body describing the retry window.","version":"0.1.0"},"servers":[{"url":"https://api.ask.dev.ai71services.ai"}],"paths":{"/v1/agents":{"post":{"tags":["Agents"],"summary":"Create Agent","description":"Create a new AI agent with custom settings and permissions.\n\nAgents can be configured with:\n- **Custom instructions**: Define the agent's behavior and expertise\n- **LLM model selection**: Choose the appropriate model for the task\n- **Creativity level**: Control response determinism (`deterministic`, `creative`, `factual`, `balance`)\n- **Collection access**: Grant access to all collections or specific ones\n\nThe created agent can be used in conversations to interact with users\nand process documents from assigned collections.","operationId":"create_agent_v1_agents_post","security":[{"X-API-Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"},"examples":{"basic":{"summary":"Create a basic agent","value":{"title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","use_all_collections":true,"settings":{"instruction":"You are a helpful customer support agent. Be polite and professional.","llm_model":"Claude Sonnet 4","creativity_level":"balance"}}},"with_collections":{"summary":"Create agent with specific collections","value":{"title":"DocumentAnalyzerAgent","description":"Analyzes documents from specific collections","use_all_collections":false,"collection_ids":["col_123abc456def","col_789ghi012jkl"],"settings":{"instruction":"Analyze documents and provide detailed insights","llm_model":"Claude Sonnet 4","creativity_level":"factual"}}}}}}},"responses":{"201":{"description":"Agent created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAgentRead","properties":{"id":{"description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Id","type":"string"},"use_all_collections":{"description":"Whether agent has access to all collections. If true collection_ids is ignored.","examples":[false],"title":"Use All Collections","type":"boolean"},"collection_ids":{"description":"List of specific collection IDs accessible to agent","examples":[["col_123abc456def","col_789ghi012jkl"]],"items":{"type":"string"},"title":"Collection Ids","type":"array"},"created_at":{"description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Created At","type":"string"},"created_by":{"description":"User ID of the creator","examples":[1001],"title":"Created By","type":"integer"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"],"title":"Description"},"is_deleted":{"description":"Whether the agent has been deleted","examples":[false],"title":"Is Deleted","type":"boolean"},"org_id":{"description":"Organization ID the agent belongs to","examples":[101],"title":"Org Id","type":"integer"},"settings":{"$ref":"#/components/schemas/SettingsRead","description":"Agent configuration settings"},"title":{"description":"Display name of the agent","examples":["Customer Support Agent"],"title":"Title","type":"string"},"updated_at":{"description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T10:30:15.123456Z"],"title":"Updated At","type":"string"}},"required":["id","use_all_collections","created_at","created_by","is_deleted","org_id","settings","title","updated_at"],"title":"SingleAgentRead","type":"object"},"examples":{"success":{"summary":"Successfully created agent","value":{"_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","use_all_collections":true,"collection_ids":[],"created_at":"2025-10-10T08:44:27.781137Z","created_by":1001,"is_deleted":false,"org_id":101,"settings":{"creativity_level":"balance","instruction":"You are a helpful customer support agent","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T08:44:27.781137Z"}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"get":{"tags":["Agents"],"summary":"List Agents","description":"Get paginated list of agents for the authenticated user.\n\nSupports:\n- **Pagination**: Control page size and number\n- **Search**: Filter agents by title or description\n- **Sorting**: Order by created_at, updated_at, title, or recently_used\n\nReturns basic agent information including title, description, icon details,\nand timestamps.","operationId":"list_agents_v1_agents_get","security":[{"X-API-Key":[]}],"parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Search query to filter agents by title or description","examples":["support"],"title":"Search"},"description":"Search query to filter agents by title or description"},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AgentSort","description":"Field to sort by","examples":["created_at"],"default":"created_at"},"description":"Field to sort by"},{"name":"sort_direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AgentSortDirection","description":"Sort order: 'asc' for ascending or 'desc' for descending","examples":["desc"],"default":"desc"},"description":"Sort order: 'asc' for ascending or 'desc' for descending"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for pagination","examples":[1],"default":1,"title":"Page"},"description":"Page number for pagination"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","examples":[10],"default":10,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"include_created_by","in":"query","required":false,"schema":{"type":"boolean","description":"Include creator info for each agent","default":true,"title":"Include Created By"},"description":"Include creator info for each agent"}],"responses":{"200":{"description":"Successfully retrieved paginated list of agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList","description":"Model for agent list response.","properties":{"data":{"description":"List of agents","items":{"$ref":"#/components/schemas/AgentRead"},"title":"Data","type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination information"}},"required":["data","pagination"],"title":"AgentList","type":"object"},"examples":{"success":{"summary":"Successfully retrieved agents","value":{"data":[{"_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","role":"assistant","created_at":"2025-10-10T08:44:27.781137Z"},{"_id":"f9e8d7c6-b5a4-3210-9876-543210fedcba","title":"DocumentAnalyzerAgent","description":"Analyzes documents from collections","role":"assistant","created_at":"2025-10-09T15:20:10.987654Z"}],"pagination":{"page":1,"page_size":10,"total_records":2,"total_pages":1}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/agents/models":{"get":{"tags":["Agents"],"summary":"List Models","description":"List inference models for the authenticated organization.\n\nPass model name as `settings.llm_model` when creating or\nupdating an agent.","operationId":"list_models_v1_agents_models_get","responses":{"200":{"description":"Models retrieved successfully","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ModelInfo"},"type":"array","title":"Response List Models V1 Agents Models Get"},"example":[{"id":"gpt-5-3-chat","name":"GPT-5.3 Chat","description":"GPT-5.3 Instant model optimized for chat. 128k context.","supported_languages":["English"],"is_default":false},{"id":"anthropic/claude-sonnet-4","name":"Claude Sonnet 4","description":"Most advanced. Top choice for reasoning and complex work.","supported_languages":["English"],"is_default":false}]}}}},"security":[{"X-API-Key":[]}]}},"/v1/agents/{agent_id}":{"get":{"tags":["Agents"],"summary":"Get Agent","description":"Retrieve detailed information about a specific agent.\n\nReturns comprehensive agent data including:\n- Agent configuration and settings\n- Collection access permissions\n- LLM model and creativity level\n- Conversation count and usage statistics\n- Creation and update timestamps","operationId":"get_agent_by_id_v1_agents__agent_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Agent Id"},"description":"Unique identifier of the agent"}],"responses":{"200":{"description":"Successfully retrieved agent details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAgentRead","properties":{"id":{"description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Id","type":"string"},"use_all_collections":{"description":"Whether agent has access to all collections. If true collection_ids is ignored.","examples":[false],"title":"Use All Collections","type":"boolean"},"collection_ids":{"description":"List of specific collection IDs accessible to agent","examples":[["col_123abc456def","col_789ghi012jkl"]],"items":{"type":"string"},"title":"Collection Ids","type":"array"},"created_at":{"description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Created At","type":"string"},"created_by":{"description":"User ID of the creator","examples":[1001],"title":"Created By","type":"integer"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"],"title":"Description"},"is_deleted":{"description":"Whether the agent has been deleted","examples":[false],"title":"Is Deleted","type":"boolean"},"org_id":{"description":"Organization ID the agent belongs to","examples":[101],"title":"Org Id","type":"integer"},"settings":{"$ref":"#/components/schemas/SettingsRead","description":"Agent configuration settings"},"title":{"description":"Display name of the agent","examples":["Customer Support Agent"],"title":"Title","type":"string"},"updated_at":{"description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T10:30:15.123456Z"],"title":"Updated At","type":"string"}},"required":["id","use_all_collections","created_at","created_by","is_deleted","org_id","settings","title","updated_at"],"title":"SingleAgentRead","type":"object"},"examples":{"basic":{"summary":"Basic agent details","value":{"_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","use_all_collections":true,"collection_ids":[],"created_at":"2025-10-10T08:44:27.781137Z","created_by":1001,"is_deleted":false,"org_id":101,"settings":{"creativity_level":"balance","instruction":"You are a helpful customer support agent","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T10:30:15.123456Z"}},"with_collections":{"summary":"Agent with collection access","value":{"_id":"f9e8d7c6-b5a4-3210-9876-543210fedcba","title":"DocumentAnalyzerAgent","description":"Analyzes documents from specific collections","use_all_collections":false,"collection_ids":["col_123abc456def","col_789ghi012jkl"],"created_at":"2025-10-09T15:20:10.987654Z","created_by":1001,"is_deleted":false,"org_id":101,"settings":{"creativity_level":"factual","instruction":"Analyze documents and provide detailed insights","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T09:15:30.456789Z"}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"patch":{"tags":["Agents"],"summary":"Update Agent","description":"Update an existing agent's configuration.\n\nSupports partial updates - only provide fields you want to change:\n- **name**: Update the agent's display name\n- **description**: Update the agent's description\n- **instructions**: Modify the agent's behavior instructions\n- **model**: Change the LLM model\n- **tools**: Update available tools\n- **file_ids**: Modify associated files\n- **metadata**: Update custom metadata\n\nAll fields are optional. Unchanged fields retain their current values.","operationId":"update_agent_v1_agents__agent_id__patch","security":[{"X-API-Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Agent Id"},"description":"Unique identifier of the agent"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreatePatch"},"examples":{"basic":{"summary":"Update agent title and description","value":{"name":"EnhancedCustomerSupportAgent","description":"An improved agent for customer support"}},"with_settings":{"summary":"Update agent settings","value":{"title":"DocumentAnalyzerProAgent","settings":{"instruction":"You are an expert document analyzer. Provide detailed analysis with citations.","creativity_level":"factual"}}},"with_collections":{"summary":"Update agent collection access","value":{"use_all_collections":false,"collection_ids":["col_123abc456def","col_789ghi012jkl"]}}}}}},"responses":{"200":{"description":"Agent updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAgentRead","properties":{"id":{"description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Id","type":"string"},"use_all_collections":{"description":"Whether agent has access to all collections. If true collection_ids is ignored.","examples":[false],"title":"Use All Collections","type":"boolean"},"collection_ids":{"description":"List of specific collection IDs accessible to agent","examples":[["col_123abc456def","col_789ghi012jkl"]],"items":{"type":"string"},"title":"Collection Ids","type":"array"},"created_at":{"description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Created At","type":"string"},"created_by":{"description":"User ID of the creator","examples":[1001],"title":"Created By","type":"integer"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"],"title":"Description"},"is_deleted":{"description":"Whether the agent has been deleted","examples":[false],"title":"Is Deleted","type":"boolean"},"org_id":{"description":"Organization ID the agent belongs to","examples":[101],"title":"Org Id","type":"integer"},"settings":{"$ref":"#/components/schemas/SettingsRead","description":"Agent configuration settings"},"title":{"description":"Display name of the agent","examples":["Customer Support Agent"],"title":"Title","type":"string"},"updated_at":{"description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T10:30:15.123456Z"],"title":"Updated At","type":"string"}},"required":["id","use_all_collections","created_at","created_by","is_deleted","org_id","settings","title","updated_at"],"title":"SingleAgentRead","type":"object"},"examples":{"basic":{"summary":"Basic agent details","value":{"_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","use_all_collections":true,"collection_ids":[],"created_at":"2025-10-10T08:44:27.781137Z","created_by":1001,"is_deleted":false,"org_id":101,"settings":{"creativity_level":"balance","instruction":"You are a helpful customer support agent","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T10:30:15.123456Z"}},"with_collections":{"summary":"Agent with collection access","value":{"_id":"f9e8d7c6-b5a4-3210-9876-543210fedcba","title":"DocumentAnalyzerAgent","description":"Analyzes documents from specific collections","use_all_collections":false,"collection_ids":["col_123abc456def","col_789ghi012jkl"],"created_at":"2025-10-09T15:20:10.987654Z","created_by":1001,"is_deleted":false,"org_id":101,"settings":{"creativity_level":"factual","instruction":"Analyze documents and provide detailed insights","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T09:15:30.456789Z"}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"delete":{"tags":["Agents"],"summary":"Delete Agent","description":"Soft-delete an agent by marking it as deleted.\n\nThe agent is not permanently removed but marked as deleted (is_deleted=True).\nThis preserves:\n- Historical conversation data\n- Agent configuration for audit purposes\n- References in existing conversations\n\nThe agent will no longer appear in active agent lists and cannot be used\nfor new conversations. Existing conversations with this agent remain accessible.","operationId":"delete_agent_v1_agents__agent_id__delete","security":[{"X-API-Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Agent Id"},"description":"Unique identifier of the agent"}],"responses":{"200":{"description":"Agent deleted successfully (soft delete)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAgentRead","properties":{"id":{"description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"],"title":"Id","type":"string"},"use_all_collections":{"description":"Whether agent has access to all collections. If true collection_ids is ignored.","examples":[false],"title":"Use All Collections","type":"boolean"},"collection_ids":{"description":"List of specific collection IDs accessible to agent","examples":[["col_123abc456def","col_789ghi012jkl"]],"items":{"type":"string"},"title":"Collection Ids","type":"array"},"created_at":{"description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Created At","type":"string"},"created_by":{"description":"User ID of the creator","examples":[1001],"title":"Created By","type":"integer"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"],"title":"Description"},"is_deleted":{"description":"Whether the agent has been deleted","examples":[false],"title":"Is Deleted","type":"boolean"},"org_id":{"description":"Organization ID the agent belongs to","examples":[101],"title":"Org Id","type":"integer"},"settings":{"$ref":"#/components/schemas/SettingsRead","description":"Agent configuration settings"},"title":{"description":"Display name of the agent","examples":["Customer Support Agent"],"title":"Title","type":"string"},"updated_at":{"description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T10:30:15.123456Z"],"title":"Updated At","type":"string"}},"required":["id","use_all_collections","created_at","created_by","is_deleted","org_id","settings","title","updated_at"],"title":"SingleAgentRead","type":"object"},"examples":{"success":{"summary":"Successfully deleted agent","value":{"_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","title":"CustomerSupportAgent","description":"An agent that helps with customer support queries","use_all_collections":true,"collection_ids":[],"created_at":"2025-10-10T08:44:27.781137Z","created_by":1001,"is_deleted":true,"org_id":101,"settings":{"creativity_level":"balance","instruction":"You are a helpful customer support agent","llm_model":"anthropic/claude-sonnet-4"},"updated_at":"2025-10-10T12:00:00.000000Z"}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/conversations":{"get":{"tags":["Conversations"],"summary":"List Conversations","description":"Get paginated conversations for the authenticated user.\n\nRetrieves all conversations accessible to the user with support for:\n- **Pagination**: Control page size and number\n- **Search**: Filter conversations by title\n- **Sorting**: Order by any field in ascending or descending order\n\nReturns a list of conversations with metadata including agent info,\ntimestamps, collection associations, and pagination details.","operationId":"get_conversations_for_user_v1_conversations_get","security":[{"X-API-Key":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for pagination","examples":[1],"default":1,"title":"Page"},"description":"Page number for pagination"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","examples":[10],"default":10,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Search term to filter conversations by title","examples":["weather"],"title":"Search"},"description":"Search term to filter conversations by title"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Field to sort by","examples":["created_at"],"default":"created_at","title":"Sort"},"description":"Field to sort by"},{"name":"sort_direction","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","description":"Sort order: 'asc' for ascending or 'desc' for descending","examples":["desc"],"default":"desc","title":"Sort Direction"},"description":"Sort order: 'asc' for ascending or 'desc' for descending"},{"name":"source_channels","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated source channels to filter by (e.g. 'web')","examples":["web"],"title":"Source Channels"},"description":"Comma-separated source channels to filter by (e.g. 'web')"}],"responses":{"200":{"description":"Successfully retrieved paginated list of conversations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversations","description":"Model for conversations list response.","properties":{"data":{"description":"List of conversations","items":{"$ref":"#/components/schemas/ConversationRead"},"title":"Data","type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination information"}},"required":["data","pagination"],"title":"Conversations","type":"object"},"examples":{"success":{"summary":"Successful response with conversations","value":{"data":[{"conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","name":"Weather Discussion","owner":334067997469574321,"created_at":"2025-10-10T08:44:27.781137Z","updated_at":"2025-10-10T09:15:43.123456Z","is_enabled":true,"is_incognito":false,"last_activity":"2025-10-10T09:15:43.123456Z"},{"conversation_id":"d5c23b4f-b567-8901-e23f-2ade31e0edcc","agent_id":"1f657e35-0fb4-52g8-0b3g-22b9ccd3271f","name":"Document Analysis","owner":334067997469574321,"collection_id":"col_123abc456def","created_at":"2025-10-09T14:20:15.234567Z","updated_at":"2025-10-09T16:45:32.345678Z","is_enabled":true,"is_incognito":true,"last_activity":"2025-10-09T16:45:32.345678Z"}],"pagination":{"page":1,"page_size":10,"total_records":15,"total_pages":2}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"post":{"tags":["Conversations"],"summary":"Send Message","description":"Send a message to an AI agent and receive a response.\n\nCreates a new conversation if `conversation_id` is not provided, or continues\nan existing conversation. Supports both streaming and non-streaming responses.\n\n**Streaming Mode** (`stream: true`):\n- Returns `text/event-stream` content type\n- Real-time Server-Sent Events (SSE)\n- Event types include:\n    - `metadata`: Initial message metadata\n    - `conversation_created`: New conversation info (if created)\n    - `thought_chunk`: Agent's reasoning process\n    - `tool_call`: Tool invocation details\n    - `tool_intervention_required`: Approval requested for a tool call\n    - `tool_intervention_resolution`: Result of the approval decision\n    - `tool_output`: Tool execution results\n    - `message`: Response content chunks\n    - `close`: Stream completion signal\n\n**Non-Streaming Mode** (`stream: false` or omitted):\n- Returns `application/json` content type\n- Complete response with full message content\n- Includes conversation_id and message_id\n\n**Optional Parameters**:\n- `collection_id`: Reference documents from a specific collection\n- `uploads`: List of file upload metadata for live file uploads (document IDs from KMS)\n- `is_incognito`: Private mode (not saved to history)\n- `message_only`: Return only message content without thoughts/steps\n- `run_in_background`: Return HTTP 202 immediately and finish processing in-process\n- `bypass_tool_approval`: Automatically approve eligible tools (default: `true`). Set to `false` to require approval.","operationId":"send_message_to_agent_v1_conversations_post","security":[{"X-API-Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageCreate"},"examples":{"non_streaming":{"summary":"Send a non-streaming message","description":"Creates or continues a conversation with immediate response","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"What is the weather in Tokyo?","stream":false,"conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","is_incognito":false,"message_only":false}},"streaming":{"summary":"Send a streaming message","description":"Creates or continues a conversation with real-time streaming response","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"Tell me the latest news","stream":true,"is_incognito":false}},"with_tool_approval":{"summary":"Send a message that requires tool approval","description":"Streams tool approval requests for the client to resolve instead of automatically approving them","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"Find the latest account activity","stream":true,"bypass_tool_approval":false}},"with_user_context":{"summary":"Send message with user context","description":"Send a message with user context","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"What do you know about me?","user_context":{"context_mode":"custom","custom_context":{"name":"John Doe","location":"New York"}}}},"with_collection":{"summary":"Send message with collection context","description":"Send a message referencing a specific document collection","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"Summarize the documents in this collection","stream":false,"collection_id":"col_123abc456def","conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"}},"with_file_uploads":{"summary":"Send message with live file uploads","description":"Send a message referencing files that have already been uploaded to KMS","value":{"agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","query":"Summarize this document for me","stream":false,"collection_id":"col_123abc456def","uploads":[{"file_document_id":"doc_123abc456def","file_name":"quarterly_report.pdf","upload_type":"file"}]}}}}}},"responses":{"200":{"description":"Successful response. Returns JSON for non-streaming or Server-Sent Events for streaming requests.","content":{"application/json":{"schema":{"description":"Model for non-streaming chat response.","properties":{"message":{"description":"The agent's response message content","examples":["The weather in Tokyo is currently 22°C with clear skies."],"title":"Message","type":"string"},"conversation_id":{"description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"],"title":"Conversation Id","type":"string"},"message_id":{"description":"Unique identifier of the message","examples":["ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"],"title":"Message Id","type":"string"}},"required":["message","conversation_id","message_id"],"title":"ChatResponse","type":"object"},"examples":{"success":{"summary":"Non-streaming response","value":{"message":"The weather in Tokyo is currently 22°C with clear skies and light winds.","conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","message_id":"ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"}}}},"text/event-stream":{"schema":{"type":"string"},"examples":{"streaming_events":{"summary":"Server-Sent Events stream","description":"Real-time event stream with metadata, thoughts, tool calls, and messages","value":"event: metadata\ndata: {\"message_id\": \"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb\"}\n\nevent: thought_chunk\ndata: {\"step_number\":1,\"text_chunk\":\"The user is asking for the latest news. I will use the web_search tool to find current headlines.\"}\n\nevent: tool_call\ndata: {\"tool_call_id\":\"tool_abc123\",\"mcp_name\":\"web_search\",\"tool_name\":\"web_search\",\"tool_args\":{\"query\":\"latest news headlines today\"},\"step_number\":1}\n\nevent: tool_intervention_required\ndata: {\"kind\":\"approval\",\"thread_id\":\"thread_xyz\",\"conversation_id\":\"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb\",\"expires_at\":1760086800.0,\"scope\":\"normal\",\"tool_calls\":[{\"tool_call_id\":\"tool_abc123\",\"mcp_name\":\"web_search\",\"tool_name\":\"web_search\",\"display_name\":\"Web Search\",\"metadata\":{}}]}\n\nevent: tool_intervention_resolution\ndata: {\"kind\":\"approval\",\"resolutions\":{\"tool_abc123\":\"approved\"},\"scope\":\"normal\"}\n\nevent: tool_output\ndata: {\"tool_call_id\":\"tool_abc123\",\"output\":\"{\\\"status\\\": \\\"ok\\\", \\\"data\\\": {\\\"result\\\": [{\\\"url\\\": \\\"https://www.example-news.com/story-1\\\", \\\"content\\\": \\\"Global Tech Summit kicks off in San Francisco, announcing new AI breakthroughs.\\\"}, {\\\"url\\\": \\\"https://www.example-news.com/story-2\\\", \\\"content\\\": \\\"Market update: Stocks surge as new trade deal is finalized.\\\"}], \\\"description\\\": \\\"2 result(s) for 'latest news headlines today'\\\", \\\"err\\\": null}}\"}\n\nevent: thought_chunk\ndata: {\"step_number\":2,\"text_chunk\":\"I have two main news stories: a Tech Summit and a market update. I will synthesize these into a clear summary for the user.\"}\n\nevent: message\ndata: {\"data\": \"Here are the latest news headlines for today:\\n\\n* **Global Tech Summit**: A summit in San Francisco has kicked off, announcing new breakthroughs in AI.\"}\n\nevent: message\ndata: {\"data\": \"\\n* **Market News**: Stocks have surged following the finalization of a new trade deal.\"}\n\nevent: close\ndata: [DONE]"}}}}},"202":{"description":"Request accepted for in-process background processing. The response body is empty."},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/conversations/{conversation_id}":{"get":{"tags":["Conversations"],"summary":"Get Conversation","description":"Retrieve detailed information about a specific conversation.\n\nReturns comprehensive conversation metadata including:\n- Agent/assistant information\n- Conversation settings (shared, incognito mode)\n- Timestamps (created, updated, last activity)\n- Collection association\n- Ownership information","operationId":"get_conversation_v1_conversations__conversation_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"],"title":"Conversation Id"},"description":"Unique identifier of the conversation"}],"responses":{"200":{"description":"Successfully retrieved conversation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationRead","description":"Model for reading conversation data.","properties":{"conversation_id":{"description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"],"title":"Conversation Id","type":"string"},"name":{"description":"Conversation name/title","examples":["Weather Discussion"],"title":"Name","type":"string"},"owner":{"description":"Owner user ID","examples":[334067997469574321],"title":"Owner","type":"integer"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Associated collection ID for document context","examples":["col_123abc456def"],"title":"Collection Id"},"created_at":{"description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Created At","type":"string"},"updated_at":{"description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Updated At","type":"string"},"is_enabled":{"description":"Whether the conversation is currently enabled","examples":[true],"title":"Is Enabled","type":"boolean"},"is_incognito":{"description":"Whether the conversation is in incognito/private mode","examples":[false],"title":"Is Incognito","type":"boolean"},"last_activity":{"description":"Last activity timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"],"title":"Last Activity","type":"string"}},"required":["conversation_id","name","owner","created_at","updated_at","is_enabled","is_incognito","last_activity"],"title":"ConversationRead","type":"object"},"examples":{"success":{"summary":"Detailed conversation information","value":{"conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","name":"Weather Discussion","owner":334067997469574321,"created_at":"2025-10-10T08:44:27.781137Z","updated_at":"2025-10-10T09:15:43.123456Z","is_enabled":true,"is_incognito":false,"last_activity":"2025-10-10T09:15:43.123456Z"}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/conversations/with-uploads":{"post":{"tags":["Conversations"],"summary":"Send Message with File Upload","description":"Upload files and send a message with file attachments in a single request.\n\nCombines document upload to KMS and message sending into one API call:\n1. **Resolves a collection** for the uploaded files\n2. **Uploads each file** to KMS (initiate → blob storage → queue for processing)\n3. **Sends the message** with file metadata to the agent\n\n**Collection Resolution Order:**\n- Uses `collection_id` if explicitly provided\n- Falls back to the conversation's existing `collection_id` (if `conversation_id` given)\n- Creates a new hidden collection with `quick` parsing strategy as last resort\n\n**Response format** is identical to the Send Message endpoint:\n- **Streaming** (`stream: true`): Server-Sent Events\n- **Non-streaming** (`stream: false`): JSON with message, conversation_id, message_id\n- **Background** (`run_in_background: true`): Empty HTTP 202 response; processing continues in-process","operationId":"send_message_with_files_v1_conversations_with_uploads_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_send_message_with_files_v1_conversations_with_uploads_post"}}},"required":true},"responses":{"200":{"description":"Files uploaded and message sent successfully. Returns JSON for non-streaming or Server-Sent Events for streaming requests.","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"The agent's response message content","examples":["The weather in Tokyo is currently 22°C with clear skies."]},"conversation_id":{"type":"string","title":"Conversation Id","description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"]},"message_id":{"type":"string","title":"Message Id","description":"Unique identifier of the message","examples":["ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"]}},"type":"object","required":["message","conversation_id","message_id"],"title":"ChatResponse","description":"Model for non-streaming chat response."},"examples":{"success":{"summary":"Non-streaming response with file upload","value":{"message":"Based on the uploaded document, here is a summary of the quarterly report...","conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","message_id":"ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"}}}},"text/event-stream":{"schema":{"type":"string"},"examples":{"streaming_events":{"summary":"Server-Sent Events stream","description":"Same event format as the Send Message endpoint","value":"event: metadata\ndata: {\"message_id\": \"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb\"}\n\nevent: message\ndata: {\"data\": \"Based on the uploaded document, here is a summary...\"}\n\nevent: close\ndata: [DONE]"}}}}},"202":{"description":"Request accepted for in-process background upload and message processing. The response body is empty."},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}},"security":[{"X-API-Key":[]}]}},"/v1/conversations/{conversation_id}/messages/{message_id}/tool-interventions":{"post":{"tags":["Conversations"],"summary":"Submit Tool Approval Decisions","description":"Approve or deny tool calls for a waiting conversation message.\n\nStart the conversation with `stream: true` and `bypass_tool_approval: false`.\nWhen the stream emits `tool_intervention_required`, map each emitted `tool_call_id`\nto a resolution: `approved`, `denied`, or `always_allow`, then submit the map here. The\noriginal stream continues after the Assistant service processes the decisions.\n\nFor `kind: activation` (the agent needs the user to connect a connector), connect it with\n`POST /v1/connectors/{connector_id}/activate`, then submit `activated`, or `canceled` if the\nuser gives up. The Assistant service treats an unanswered activation as `canceled` after\n`expires_at`.","operationId":"submit_tool_approval_decisions_v1_conversations__conversation_id__messages__message_id__tool_interventions_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the conversation waiting for tool approval","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"],"title":"Conversation Id"},"description":"Unique identifier of the conversation waiting for tool approval"},{"name":"message_id","in":"path","required":true,"schema":{"type":"string","description":"Message ID from the stream metadata event","examples":["ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"],"title":"Message Id"},"description":"Message ID from the stream metadata event"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolApprovalRequest"}}}},"responses":{"200":{"description":"Tool approval resolutions accepted. The Assistant service resumes the waiting message stream after processing the resolutions.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Submit Tool Approval Decisions V1 Conversations  Conversation Id  Messages  Message Id  Tool Interventions Post"},"example":{}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/conversations/{conversation_id}/messages":{"get":{"tags":["Conversations"],"summary":"List Messages","description":"Get paginated list of messages for a specific conversation.\n\nReturns messages in chronological order with complete information including:\n- User queries and agent responses\n- Agent thoughts and reasoning steps\n- Tool calls and their outputs\n- Message metadata (timestamps, IDs, sender type)\n- File uploads and attachments\n- User feedback (upvotes/downvotes)\n\nMessages are returned with pagination support for efficient loading\nof long conversation histories.","operationId":"get_messages_for_conversation_v1_conversations__conversation_id__messages_get","security":[{"X-API-Key":[]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"],"title":"Conversation Id"},"description":"Unique identifier of the conversation"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for pagination","examples":[1],"default":1,"title":"Page"},"description":"Page number for pagination"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of messages per page (max 100)","examples":[10],"default":10,"title":"Page Size"},"description":"Number of messages per page (max 100)"}],"responses":{"200":{"description":"Successfully retrieved paginated list of messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessages","properties":{"data":{"description":"List of messages for conversation","items":{"$ref":"#/components/schemas/Message"},"title":"Data","type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of messages"}},"required":["data","pagination"],"title":"ConversationMessages","type":"object"},"examples":{"success":{"summary":"List of messages with details","value":{"data":[{"conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","message_id":"msg_user_001","sender_type":"user","message":"What is the weather in Tokyo?","created_at":"2025-10-10T08:44:27.781137Z","is_deleted":false,"steps":[],"agent_name":"web-searcher","uploads":[]},{"conversation_id":"c4b12a3e-a456-7890-d12e-1fdd20d9dcbb","message_id":"ae0acbe8-ec77-4231-911a-2fdd20d9dcbb","parent_message_id":"msg_user_001","sender_type":"agent","agent_id":"0e546d24-09a3-41f7-9a2f-11a8bbc2160e","message":"The weather in Tokyo is currently 22°C with clear skies and light winds.","created_at":"2025-10-10T08:44:35.891234Z","is_deleted":false,"feedback":{"sources":["https://weather.example.com/tokyo"],"vote":"UPVOTE"},"thoughts":"User is asking about weather. I should use web search to get current information.","steps":[{"step_number":1,"tool_name":"web_search","tool_call_id":"tool_abc123","tool_args":{"query":"weather Tokyo current"},"tool_output":"Temperature: 22°C, Conditions: Clear"}],"agent_name":"web-searcher","uploads":[]}],"pagination":{"page":1,"page_size":10,"total_records":8,"total_pages":1}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/collections":{"post":{"tags":["Collections"],"summary":"Create Collection","description":"Create a new document collection.\n\nCollections organize documents and can be configured with:\n- **name**: Display name for the collection\n- **description**: Optional description\n- **Visibility**: Control whether the collection is hidden","operationId":"create_collection_v1_collections_post","security":[{"X-API-Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreateRequest"},"examples":{"basic":{"summary":"Create a basic collection","value":{"name":"Project Documents","description":"Collection of project-related documents","is_hidden":false}},"hidden":{"summary":"Create a hidden collection","value":{"name":"Internal Documents","description":"Hidden collection for internal use","is_hidden":true}}}}}},"responses":{"200":{"description":"Collection created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse","description":"Response model for collection operations.","properties":{"id":{"examples":["1"],"title":"Id","type":"string"},"name":{"examples":["Project Documents"],"maxLength":255,"minLength":1,"title":"Name","type":"string"},"description":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"examples":["Collection of project documents"],"title":"Description"},"is_hidden":{"default":false,"title":"Is Hidden","type":"boolean"},"organization_id":{"default":"0","examples":["101"],"title":"Organization Id","type":"string"},"created_by":{"default":"0","examples":["1001"],"title":"Created By","type":"string"},"document_count":{"description":"Count of active documents in the collection","examples":[5],"title":"Document Count","type":"integer"},"data_source_types":{"examples":[["upload_file","google_drive"]],"items":{"type":"string"},"maxItems":100,"title":"Data Source Types","type":"array"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Role of the current user on the collection","examples":["editor"],"title":"Role"},"share_status":{"default":"Private","description":"Indicates sharing status of the collection","examples":["Private"],"title":"Share Status","type":"string"},"created_at":{"examples":[1739429535],"title":"Created At","type":"integer"},"updated_at":{"examples":[1739429535],"title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","name","document_count","data_source_types","created_at","updated_at"],"title":"CollectionResponse","type":"object"},"examples":{"success":{"summary":"Successfully created collection","value":{"id":"col_123abc456def","name":"Project Documents","description":"Collection of project-related documents","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":0,"data_source_types":[],"role":"owner","share_status":"Private","created_at":1739429535,"updated_at":1739429535,"is_deleted":false}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"get":{"tags":["Collections"],"summary":"List Collections","description":"Get paginated list of collections accessible to the authenticated user.\n\nSupports:\n- **Pagination**: Control page size and number\n- **Search**: Filter collections by name\n- **Sorting**: Order by various fields with custom priority\n- **Filtering**: Include/exclude deleted and hidden collections\n\nReturns collection metadata including document counts, sharing status,\nprocessing settings, and data source types.","operationId":"get_collections_v1_collections_get","security":[{"X-API-Key":[]}],"parameters":[{"name":"collection_ids_to_sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Optional list of collection IDs to prioritize in sorting","title":"Collection Ids To Sort By"},"description":"Optional list of collection IDs to prioritize in sorting"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for pagination","examples":[1],"default":1,"title":"Page"},"description":"Page number for pagination"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","examples":[30],"default":30,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Search term to filter collections by name","examples":["project"],"title":"Search"},"description":"Search term to filter collections by name"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Field to sort by","examples":["updated_at"],"default":"updated_at","title":"Sort By"},"description":"Field to sort by"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: 'asc' or 'desc'","examples":["desc"],"default":"desc","title":"Sort Order"},"description":"Sort order: 'asc' or 'desc'"},{"name":"get_deleted_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return only deleted (archived) collections","examples":[false],"default":false,"title":"Get Deleted Only"},"description":"Return only deleted (archived) collections"},{"name":"include_hidden","in":"query","required":false,"schema":{"type":"boolean","description":"Include hidden collections in results","examples":[false],"default":false,"title":"Include Hidden"},"description":"Include hidden collections in results"}],"responses":{"200":{"description":"Successfully retrieved paginated list of collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionResponse","description":"Paginated response for collection list.","properties":{"data":{"description":"List of collections","items":{"$ref":"#/components/schemas/CollectionResponse"},"title":"Data","type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of collections"}},"required":["data","pagination"],"title":"PaginatedCollectionResponse","type":"object"},"examples":{"success":{"summary":"Successfully retrieved collections","value":{"data":[{"id":"col_123abc456def","name":"Project Documents","description":"Collection of project-related documents","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":15,"data_source_types":["upload_file","google_drive"],"role":"owner","share_status":"Shared","created_at":1739429535,"updated_at":1739450125,"is_deleted":false},{"id":"col_789ghi012jkl","name":"Research Papers","description":"Academic research papers collection","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":28,"data_source_types":["upload_file"],"role":"editor","share_status":"Private","created_at":1739400000,"updated_at":1739445000,"is_deleted":false}],"pagination":{"page":1,"page_size":30,"total_records":2,"total_pages":1}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"delete":{"tags":["Collections"],"summary":"Delete Collections","description":"Delete multiple collections and their documents.\n\nThis is a delete operation that:\n- Deletes collections and their associated documents in next 30 days\n- Removes collections from search results","operationId":"bulk_delete_collections_v1_collections_delete","security":[{"X-API-Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDeleteRequest"},"examples":{"single":{"summary":"Delete a single collection","value":{"collection_ids":["col_123abc456def"]}},"multiple":{"summary":"Delete multiple collections","value":{"collection_ids":["col_123abc456def","col_789ghi012jkl","col_456mno789pqr"]}}}}}},"responses":{"200":{"description":"Collections deleted successfully (archived)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CollectionResponse","description":"Response model for collection operations.","properties":{"id":{"examples":["1"],"title":"Id","type":"string"},"name":{"examples":["Project Documents"],"maxLength":255,"minLength":1,"title":"Name","type":"string"},"description":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"examples":["Collection of project documents"],"title":"Description"},"is_hidden":{"default":false,"title":"Is Hidden","type":"boolean"},"organization_id":{"default":"0","examples":["101"],"title":"Organization Id","type":"string"},"created_by":{"default":"0","examples":["1001"],"title":"Created By","type":"string"},"document_count":{"description":"Count of active documents in the collection","examples":[5],"title":"Document Count","type":"integer"},"data_source_types":{"examples":[["upload_file","google_drive"]],"items":{"type":"string"},"maxItems":100,"title":"Data Source Types","type":"array"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Role of the current user on the collection","examples":["editor"],"title":"Role"},"share_status":{"default":"Private","description":"Indicates sharing status of the collection","examples":["Private"],"title":"Share Status","type":"string"},"created_at":{"examples":[1739429535],"title":"Created At","type":"integer"},"updated_at":{"examples":[1739429535],"title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","name","document_count","data_source_types","created_at","updated_at"],"title":"CollectionResponse","type":"object"},"title":"Response Bulk Delete Collections V1 Collections Delete"},"examples":{"success":{"summary":"Successfully deleted collections","value":[{"id":"col_123abc456def","name":"Project Documents","description":"Collection of project-related documents","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":15,"data_source_types":["upload_file"],"role":"owner","share_status":"Private","created_at":1739429535,"updated_at":1739460000,"is_deleted":true}]}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/collections/{collection_id}":{"get":{"tags":["Collections"],"summary":"Get Collection","description":"Retrieve detailed information about a specific collection.\n\nReturns comprehensive collection data including:\n- Processing configuration (embedding model, parsing, chunking)\n- Document counts (active and total)\n- Data source types (upload_file, google_drive, etc.)\n- Sharing status and user role\n- Creation and update timestamps\n- Visibility settings","operationId":"get_collection_v1_collections__collection_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the collection","examples":["col_123abc456def"],"title":"Collection Id"},"description":"Unique identifier of the collection"}],"responses":{"200":{"description":"Successfully retrieved collection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse","description":"Response model for collection operations.","properties":{"id":{"examples":["1"],"title":"Id","type":"string"},"name":{"examples":["Project Documents"],"maxLength":255,"minLength":1,"title":"Name","type":"string"},"description":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"examples":["Collection of project documents"],"title":"Description"},"is_hidden":{"default":false,"title":"Is Hidden","type":"boolean"},"organization_id":{"default":"0","examples":["101"],"title":"Organization Id","type":"string"},"created_by":{"default":"0","examples":["1001"],"title":"Created By","type":"string"},"document_count":{"description":"Count of active documents in the collection","examples":[5],"title":"Document Count","type":"integer"},"data_source_types":{"examples":[["upload_file","google_drive"]],"items":{"type":"string"},"maxItems":100,"title":"Data Source Types","type":"array"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Role of the current user on the collection","examples":["editor"],"title":"Role"},"share_status":{"default":"Private","description":"Indicates sharing status of the collection","examples":["Private"],"title":"Share Status","type":"string"},"created_at":{"examples":[1739429535],"title":"Created At","type":"integer"},"updated_at":{"examples":[1739429535],"title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","name","document_count","data_source_types","created_at","updated_at"],"title":"CollectionResponse","type":"object"},"examples":{"success":{"summary":"Collection details","value":{"id":"col_123abc456def","name":"Project Documents","description":"Collection of project-related documents","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":15,"data_source_types":["upload_file","google_drive"],"role":"owner","share_status":"Shared","created_at":1739429535,"updated_at":1739450125,"is_deleted":false}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"patch":{"tags":["Collections"],"summary":"Update Collection","description":"Update an existing collection's metadata.\n\nSupports partial updates for:\n- **name**: Update the collection's display name\n- **description**: Modify the collection's description\n\nNote: Processing settings (embedding model, parsing strategy, etc.) cannot be\nchanged after creation to maintain consistency of processed documents.","operationId":"update_collection_v1_collections__collection_id__patch","security":[{"X-API-Key":[]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the collection","examples":["col_123abc456def"],"title":"Collection Id"},"description":"Unique identifier of the collection"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdate"},"examples":{"basic":{"summary":"Update collection name and description","value":{"name":"Updated Project Documents","description":"Updated description for project documents"}},"name_only":{"summary":"Update only the name","value":{"name":"New Collection Name"}}}}}},"responses":{"200":{"description":"Collection updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse","description":"Response model for collection operations.","properties":{"id":{"examples":["1"],"title":"Id","type":"string"},"name":{"examples":["Project Documents"],"maxLength":255,"minLength":1,"title":"Name","type":"string"},"description":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"examples":["Collection of project documents"],"title":"Description"},"is_hidden":{"default":false,"title":"Is Hidden","type":"boolean"},"organization_id":{"default":"0","examples":["101"],"title":"Organization Id","type":"string"},"created_by":{"default":"0","examples":["1001"],"title":"Created By","type":"string"},"document_count":{"description":"Count of active documents in the collection","examples":[5],"title":"Document Count","type":"integer"},"data_source_types":{"examples":[["upload_file","google_drive"]],"items":{"type":"string"},"maxItems":100,"title":"Data Source Types","type":"array"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Role of the current user on the collection","examples":["editor"],"title":"Role"},"share_status":{"default":"Private","description":"Indicates sharing status of the collection","examples":["Private"],"title":"Share Status","type":"string"},"created_at":{"examples":[1739429535],"title":"Created At","type":"integer"},"updated_at":{"examples":[1739429535],"title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","name","document_count","data_source_types","created_at","updated_at"],"title":"CollectionResponse","type":"object"},"examples":{"success":{"summary":"Collection details","value":{"id":"col_123abc456def","name":"Project Documents","description":"Collection of project-related documents","is_hidden":false,"organization_id":"101","created_by":"1001","document_count":15,"data_source_types":["upload_file","google_drive"],"role":"owner","share_status":"Shared","created_at":1739429535,"updated_at":1739450125,"is_deleted":false}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/documents/upload":{"post":{"tags":["Documents"],"summary":"Upload Document","description":"Upload a document directly to a collection.\n\nProvide either `collection_id` or `collection_name`. If only `collection_name`\nis given, the system resolves it to a single collection — errors if zero or\nmultiple matches are found.\n\n**Processing statuses:**\n- `uploading`: Initial state during upload\n- `queued`: Waiting for processing\n- `processing`: Currently being processed\n- `ready`: Available for search and retrieval\n- `failed`: Processing failed (can retry)\n- `upload_failed_duplicate_content`: Duplicate content detected\n\n**Allowed file formats:**\n- `.pdf`, `.doc`, `.docx`, `.txt`, `.md`, `.markdown`, `.json`, `.xml`, `.csv`, `.tsv`, `.xls`, `.xlsm`, `.xlsx`, `.pptx`, `.ppt`, `.jpg`, `.jpeg`, `.png`, `.html`","operationId":"upload_document_v1_documents_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_v1_documents_upload_post"}}},"required":true},"responses":{"200":{"description":"Document upload initiated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse","properties":{"status":{"type":"string","title":"Status","examples":["uploading"]},"document_name":{"type":"string","title":"Document Name","default":"","examples":["document.pdf"]},"file_hash":{"type":"string","title":"File Hash","default":"","examples":["hash-value"]},"body":{"anyOf":[{"$ref":"#/components/schemas/SuccessDocumentUploadResponse"},{"$ref":"#/components/schemas/FailedDocumentUploadInitiateResponse"}],"title":"Body","description":"document details"}},"type":"object","required":["status","body"],"title":"DocumentUploadResponse","description":"Response model for document upload."},"examples":{"success":{"summary":"Successfully uploaded document","value":{"status":"queued","document_name":"project_report.pdf","file_hash":"a1b2c3d4e5f67890","body":{"document_id":"doc_123abc456def"}}},"duplicate":{"summary":"Duplicate document detected","value":{"status":"upload_failed_duplicate_content","document_name":"duplicate.pdf","file_hash":"a1b2c3d4e5f67890","body":{"error_message":"Document with same content already exists"}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}},"security":[{"X-API-Key":[]}],"x-codeSamples":[{"lang":"Python","label":"Requests","source":"import requests\n\nurl = \"https://api.ask.dev.ai71services.ai/v1/documents/upload\"\nheaders = {\"x-api-key\": \"YOUR_API_KEY\"}\n\n# Open the file in binary mode\nwith open(\"/path/to/document.pdf\", \"rb\") as f:\n    files = {\"file\": (\"document.pdf\", f, \"application/octet-stream\")}\n    data = {\"collection_id\": \"your-collection-id\"}\n\n    response = requests.post(url, headers=headers, files=files, data=data)\n    print(response.json())\n"},{"lang":"cURL","label":"cURL","source":"curl -X POST \"https://api.ask.dev.ai71services.ai/v1/documents/upload\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -F \"file=@/path/to/document.pdf\" \\\n  -F \"collection_id=your-collection-id\"\n"},{"lang":"JavaScript","label":"Fetch API","source":"const formData = new FormData();\nformData.append(\"file\", fileInput.files[0]);\nformData.append(\"collection_id\", \"your-collection-id\");\n\nfetch(\"https://api.ask.dev.ai71services.ai/v1/documents/upload\", {\n  method: \"POST\",\n  headers: { \"x-api-key\": \"YOUR_API_KEY\" },\n  body: formData\n})\n  .then(response => response.json())\n  .then(data => console.log(data));\n"}]}},"/v1/documents":{"get":{"tags":["Documents"],"summary":"List Documents","description":"Get paginated and filterable list of all documents.\n\nSupports extensive filtering and sorting:\n- **Pagination**: Control page size and number\n- **Search**: Filter by filename\n- **Collections**: Filter by one or more collections, or by collection name\n- **File types**: Filter by document format\n- **Processing status**: Filter by processing state\n- **Metadata**: Filter by document metadata key-value pairs\n- **Date range**: Filter by update timestamps\n- **Deleted**: Include or exclude archived documents\n\nReturns document metadata including processing status, file information,\nand collection association.","operationId":"get_documents_v1_documents_get","security":[{"X-API-Key":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number for pagination","examples":[1],"default":1,"title":"Page"},"description":"Page number for pagination"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page (max 100)","examples":[30],"default":30,"title":"Page Size"},"description":"Number of items per page (max 100)"},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Search term to filter documents by filename","examples":["report"],"title":"Search"},"description":"Search term to filter documents by filename"},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["name","created_at","updated_at","id"],"type":"string","description":"Field to sort by","examples":["updated_at"],"default":"updated_at","title":"Sort By"},"description":"Field to sort by"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: 'asc' or 'desc'","examples":["desc"],"default":"desc","title":"Sort Order"},"description":"Sort order: 'asc' or 'desc'"},{"name":"collection_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Filter by collection IDs","title":"Collection Ids"},"description":"Filter by collection IDs"},{"name":"collection_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by collection name (resolves to collection ID)","title":"Collection Name"},"description":"Filter by collection name (resolves to collection ID)"},{"name":"file_types","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Filter by file types (e.g., pdf, docx)","title":"File Types"},"description":"Filter by file types (e.g., pdf, docx)"},{"name":"processing_statuses","in":"query","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentProcessingStatus"},"description":"Filter by processing status","title":"Processing Statuses"},"description":"Filter by processing status"},{"name":"filter_metadata","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}","title":"Filter Metadata"},"description":"Filter by metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}"},{"name":"updated_at_from","in":"query","required":false,"schema":{"type":"integer","description":"Filter by update timestamp (Unix timestamp)","title":"Updated At From"},"description":"Filter by update timestamp (Unix timestamp)"},{"name":"updated_at_to","in":"query","required":false,"schema":{"type":"integer","description":"Filter by update timestamp (Unix timestamp)","title":"Updated At To"},"description":"Filter by update timestamp (Unix timestamp)"},{"name":"is_deleted","in":"query","required":false,"schema":{"type":"boolean","description":"Return only deleted (archived) documents","examples":[false],"default":false,"title":"Is Deleted"},"description":"Return only deleted (archived) documents"}],"responses":{"200":{"description":"Successfully retrieved paginated list of documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedDocumentResponse","description":"Paginated response for document list.","properties":{"data":{"description":"List of documents","items":{"$ref":"#/components/schemas/DocumentResponse"},"title":"Data","type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of documents"}},"required":["data","pagination"],"title":"PaginatedDocumentResponse","type":"object"},"examples":{"success":{"summary":"Successfully retrieved documents","value":{"data":[{"id":"doc_123abc456def","filename":"project_report.pdf","file_type":"pdf","file_size":204800,"data_source_type":"upload_file","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"a1b2c3d4e5f67890","owner_id":"1001","created_at":1739429535,"updated_at":1739429600,"is_deleted":false},{"id":"doc_789ghi012jkl","filename":"meeting_notes.docx","file_type":"docx","file_size":102400,"data_source_type":"google_drive","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"f6e5d4c3b2a19876","owner_id":"1001","created_at":1739430000,"updated_at":1739430065,"is_deleted":false}],"pagination":{"page":1,"page_size":30,"total_records":2,"total_pages":1}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"delete":{"tags":["Documents"],"summary":"Delete Documents","description":"Delete documents by IDs or by filters.\n\nProvide `document_ids` to delete specific documents, **or** use filters\n(collection_name, collection_ids, search, file_types, filter_metadata)\nto find and delete matching documents.\n\nThis operation:\n- Marks documents as deleted (is_deleted=True)\n- Preserves document data for potential recovery for next 30 days\n- Removes documents from search results","operationId":"bulk_delete_documents_v1_documents_delete","security":[{"X-API-Key":[]}],"parameters":[{"name":"document_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Document IDs to delete directly","title":"Document Ids"},"description":"Document IDs to delete directly"},{"name":"collection_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: collection name","title":"Collection Name"},"description":"Filter: collection name"},{"name":"collection_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter: collection IDs","title":"Collection Ids"},"description":"Filter: collection IDs"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: search by filename","title":"Search"},"description":"Filter: search by filename"},{"name":"file_types","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter: file types (e.g. pdf, docx)","title":"File Types"},"description":"Filter: file types (e.g. pdf, docx)"},{"name":"filter_metadata","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}","title":"Filter Metadata"},"description":"Filter: metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}"}],"responses":{"200":{"description":"Documents soft-deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentProcessingResponse","description":"Response model for bulk document processing/operations (retry/cancel).","properties":{"processed_documents":{"description":"List of processed documents with their details.","items":{"$ref":"#/components/schemas/DocumentResponse"},"title":"Processed Documents","type":"array"},"skipped_documents":{"description":"List of skipped documents, each with a 'document_id' and a 'reason' (e.g., document not found, already processed, invalid state).","items":{"$ref":"#/components/schemas/SkippedDocument"},"title":"Skipped Documents","type":"array"}},"title":"DocumentProcessingResponse","type":"object"},"examples":{"success":{"summary":"Successfully deleted documents","value":{"processed_documents":[{"id":"doc_123abc456def","filename":"project_report.pdf","file_type":"pdf","file_size":204800,"data_source_type":"upload_file","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"a1b2c3d4e5f67890","owner_id":"1001","created_at":1739429535,"updated_at":1739460000,"is_deleted":true}],"skipped_documents":[]}},"partial_success":{"summary":"Some documents deleted, some skipped","value":{"processed_documents":[{"id":"doc_123abc456def","filename":"project_report.pdf","file_type":"pdf","file_size":204800,"data_source_type":"upload_file","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"a1b2c3d4e5f67890","owner_id":"1001","created_at":1739429535,"updated_at":1739460000,"is_deleted":true}],"skipped_documents":[{"document_id":"doc_missing_789ghi012jkl","reason":"Document not found"}]}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}},"patch":{"tags":["Documents"],"summary":"Update Document","description":"Update a document by ID or by query filters.\n\nProvide `document_id` to update a specific document, **or** use filters\n(collection_name, collection_ids, search, file_types, filter_metadata)\nto locate a single document. Returns an error if zero or multiple\ndocuments match the filters.\n\nSupports updating:\n- **filename**: Change the display name\n- **metadata**: Update document metadata\n- **file**: Replace document content with a new file (initiates re-processing)","operationId":"update_document_v1_documents_patch","security":[{"X-API-Key":[]}],"parameters":[{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Document ID to update directly","title":"Document Id"},"description":"Document ID to update directly"},{"name":"collection_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: collection name to find the document","title":"Collection Name"},"description":"Filter: collection name to find the document"},{"name":"collection_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter: collection IDs","title":"Collection Ids"},"description":"Filter: collection IDs"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: search by filename","title":"Search"},"description":"Filter: search by filename"},{"name":"file_types","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter: file types (e.g. pdf, docx)","title":"File Types"},"description":"Filter: file types (e.g. pdf, docx)"},{"name":"filter_metadata","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}","title":"Filter Metadata"},"description":"Filter: metadata as JSON string, e.g. {\"edgehub_internal_file_id\": \"123\"}"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_update_document_v1_documents_patch"}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse","description":"Response model for document operations.","properties":{"id":{"description":"Document ID","title":"Id","type":"string"},"filename":{"default":"","examples":["document.pdf"],"title":"Filename","type":"string"},"file_type":{"default":"","examples":["pdf"],"title":"File Type","type":"string"},"file_size":{"default":0,"examples":[204800],"title":"File Size","type":"integer"},"data_source_type":{"default":"upload_file","examples":["google_drive"],"title":"Data Source Type","type":"string"},"processing_status":{"default":"uploading","examples":["queued"],"title":"Processing Status","type":"string"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Collection ID","title":"Collection Id"},"file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["hash-value"],"title":"File Hash"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"examples":[null,{"category":"finance","source":"user"}],"title":"Metadata"},"owner_id":{"default":"0","examples":["1001"],"title":"Owner Id","type":"string"},"created_at":{"description":"Creation timestamp","title":"Created At","type":"integer"},"updated_at":{"description":"Last update timestamp","title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","created_at","updated_at"],"title":"DocumentResponse","type":"object"},"examples":{"success":{"summary":"Document details","value":{"id":"doc_123abc456def","filename":"project_report.pdf","file_type":"pdf","file_size":204800,"data_source_type":"upload_file","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"a1b2c3d4e5f67890","owner_id":"1001","created_at":1739429535,"updated_at":1739429600,"is_deleted":false}},"processing":{"summary":"Document being processed","value":{"id":"doc_456mno789pqr","filename":"large_document.pdf","file_type":"pdf","file_size":5242880,"data_source_type":"upload_file","processing_status":"processing","collection_id":"col_123abc456def","file_hash":"b2c3d4e5f6a78901","owner_id":"1001","created_at":1739429700,"updated_at":1739429750,"is_deleted":false}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document","description":"Retrieve detailed information about a specific document.\n\nReturns comprehensive document metadata including:\n- File information (name, type, size, hash)\n- Processing status and timestamps\n- Collection association\n- Data source type\n- Owner information\n- Deletion status","operationId":"get_document_v1_documents__document_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the document","examples":["doc_123abc456def"],"title":"Document Id"},"description":"Unique identifier of the document"}],"responses":{"200":{"description":"Successfully retrieved document details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse","description":"Response model for document operations.","properties":{"id":{"description":"Document ID","title":"Id","type":"string"},"filename":{"default":"","examples":["document.pdf"],"title":"Filename","type":"string"},"file_type":{"default":"","examples":["pdf"],"title":"File Type","type":"string"},"file_size":{"default":0,"examples":[204800],"title":"File Size","type":"integer"},"data_source_type":{"default":"upload_file","examples":["google_drive"],"title":"Data Source Type","type":"string"},"processing_status":{"default":"uploading","examples":["queued"],"title":"Processing Status","type":"string"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Collection ID","title":"Collection Id"},"file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["hash-value"],"title":"File Hash"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"examples":[null,{"category":"finance","source":"user"}],"title":"Metadata"},"owner_id":{"default":"0","examples":["1001"],"title":"Owner Id","type":"string"},"created_at":{"description":"Creation timestamp","title":"Created At","type":"integer"},"updated_at":{"description":"Last update timestamp","title":"Updated At","type":"integer"},"is_deleted":{"default":false,"examples":[false],"title":"Is Deleted","type":"boolean"}},"required":["id","created_at","updated_at"],"title":"DocumentResponse","type":"object"},"examples":{"success":{"summary":"Document details","value":{"id":"doc_123abc456def","filename":"project_report.pdf","file_type":"pdf","file_size":204800,"data_source_type":"upload_file","processing_status":"ready","collection_id":"col_123abc456def","file_hash":"a1b2c3d4e5f67890","owner_id":"1001","created_at":1739429535,"updated_at":1739429600,"is_deleted":false}},"processing":{"summary":"Document being processed","value":{"id":"doc_456mno789pqr","filename":"large_document.pdf","file_type":"pdf","file_size":5242880,"data_source_type":"upload_file","processing_status":"processing","collection_id":"col_123abc456def","file_hash":"b2c3d4e5f6a78901","owner_id":"1001","created_at":1739429700,"updated_at":1739429750,"is_deleted":false}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/documents/url/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document URL","description":"Retrieve a time-limited signed URL for downloading the document.\n\nThe returned URL provides direct access to the document file stored in\nobject storage. The URL is temporary and will expire after a set period.","operationId":"get_document_url_v1_documents_url__document_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the document","examples":["doc_123abc456def"],"title":"Document Id"},"description":"Unique identifier of the document"}],"responses":{"200":{"description":"Successfully retrieved signed URL","content":{"application/json":{"schema":{"type":"string","title":"Response Get Document Url V1 Documents Url  Document Id  Get"},"examples":{"success":{"summary":"Signed URL for document access","value":"https://storage.example.com/signed/path/to/document.pdf?signature=abc123..."}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/documents/retry-processing":{"post":{"tags":["Documents"],"summary":"Retry Processing","description":"Re-queue documents that failed during processing.\n\nUse this endpoint to retry documents with status:\n- `failed`: General processing failure\n- `upload_failed`: Upload to storage failed\n\nDocuments are added back to the processing queue and will be processed\naccording to the collection's settings. Not applicable for documents with\nstatus `failed and cannot retry`.","operationId":"retry_document_processing_v1_documents_retry_processing_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRetryProcessingRequest"},"examples":{"single":{"summary":"Retry processing for a single document","value":{"document_ids":["doc_456mno789pqr"]}},"multiple":{"summary":"Retry processing for multiple documents","value":{"document_ids":["doc_456mno789pqr","doc_111aaa222bbb"]}}}}},"required":true},"responses":{"200":{"description":"Document processing re-queued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentProcessingResponse","items":{"type":"string"},"type":"array"},"examples":{"success":{"summary":"Successfully re-queued documents","value":["doc_456mno789pqr"]}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}},"security":[{"X-API-Key":[]}]}},"/v1/documents/cancel-processing":{"post":{"tags":["Documents"],"summary":"Cancel Processing","description":"Cancel processing for documents that are currently being processed or queued.\n\nThis operation:\n- Stops ongoing processing for the documents\n- Marks them with status `cancelled`\n- Removes them from the processing queue\n\nUseful for stopping processing of large documents or correcting upload mistakes\nbefore processing completes.","operationId":"cancel_document_processing_v1_documents_cancel_processing_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCancelProcessingRequest"},"examples":{"single":{"summary":"Cancel processing for a single document","value":{"document_ids":["doc_456mno789pqr"]}},"multiple":{"summary":"Cancel processing for multiple documents","value":{"document_ids":["doc_456mno789pqr","doc_111aaa222bbb"]}}}}},"required":true},"responses":{"200":{"description":"Document processing cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentProcessingResponse","properties":{"processed_documents":{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array","title":"Processed Documents","description":"List of processed documents with their details."},"skipped_documents":{"items":{"$ref":"#/components/schemas/SkippedDocument"},"type":"array","title":"Skipped Documents","description":"List of skipped documents, each with a 'document_id' and a 'reason' (e.g., document not found, already processed, invalid state)."}},"type":"object","title":"DocumentProcessingResponse","description":"Response model for bulk document processing/operations (retry/cancel)."},"examples":{"success":{"summary":"Successfully cancelled processing","value":{"processed_documents":[{"id":"doc_456mno789pqr","filename":"large_document.pdf","file_type":"pdf","file_size":5000000,"data_source_type":"upload_file","processing_status":"cancelled","collection_id":"col_123abc456def","file_hash":"c3d4e5f6a7b89012","owner_id":"1001","created_at":1739430000,"updated_at":1739480000,"is_deleted":false}],"skipped_documents":[]}},"partial_success":{"summary":"Some documents cancelled, some skipped","value":{"processed_documents":[{"id":"doc_456mno789pqr","filename":"large_document.pdf","file_type":"pdf","file_size":5000000,"data_source_type":"upload_file","processing_status":"cancelled","collection_id":"col_123abc456def","file_hash":"c3d4e5f6a7b89012","owner_id":"1001","created_at":1739430000,"updated_at":1739480000,"is_deleted":false}],"skipped_documents":[{"document_id":"doc_111aaa222bbb","reason":"Document is not in a cancellable state"}]}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}},"security":[{"X-API-Key":[]}]}},"/v1/users/search":{"post":{"tags":["Permissions"],"summary":"Search Users","description":"Search users in the authenticated user's organization.\n\nSupports filtering by:\n- **name**: Filter by user display name\n- **email**: Filter by exact email address\n- **emails**: Filter by a list of email addresses\n- **user_ids**: Filter by a list of user IDs\n- **role_name**: Filter by organization role (`ask71_admin`, `organization_admin`, `member`)\n- **status**: Filter by user status (`ACTIVE`, `INACTIVE`, `INITIAL`, `LOCKED`, `DELETED`)\n- **email_or_name**: Partial match on email or display name\n\nResults are paginated and sortable.","operationId":"search_users_v1_users_search_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page number","examples":[1],"default":1,"title":"Page"},"description":"Page number"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of users per page","examples":[10],"default":10,"title":"Page Size"},"description":"Number of users per page"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Field to sort by","examples":["display_name"],"default":"display_name","title":"Sort By"},"description":"Field to sort by"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order (asc or desc)","examples":["asc"],"default":"asc","title":"Sort Order"},"description":"Sort order (asc or desc)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchUsersRequest"},"examples":{"by_name":{"summary":"Search users by name","value":{"name":"John Doe"}},"by_email_or_name":{"summary":"Search users by email or name","value":{"email_or_name":"john"}},"by_role_and_status":{"summary":"Filter users by role and status","value":{"role_name":"member","status":"ACTIVE"}}}}}},"responses":{"200":{"description":"Successfully searched users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchUsersResponse","description":"Response model for user search results.","properties":{"users":{"description":"List of users","items":{"$ref":"#/components/schemas/SearchUserItem"},"title":"Users","type":"array"},"metadata":{"$ref":"#/components/schemas/SearchUsersMetadata","description":"Pagination metadata"}},"required":["metadata"],"title":"SearchUsersResponse","type":"object"},"examples":{"success":{"summary":"Successfully searched users","value":{"users":[{"id":"1234567890","userState":"ACTIVE","email":"john.doe@example.com","firstName":"John","lastName":"Doe","displayName":"John Doe","phoneNumber":"+1234567890","isEmailVerified":true,"isPhoneVerified":false,"roles":["member"],"creationDate":"2024-07-29T15:51:28.071Z"},{"id":"9876543210","userState":"ACTIVE","email":"jane.smith@example.com","firstName":"Jane","lastName":"Smith","displayName":"Jane Smith","phoneNumber":"+0987654321","isEmailVerified":true,"isPhoneVerified":true,"roles":["organization_admin"],"creationDate":"2024-08-15T10:30:00.000Z"}],"metadata":{"total":2,"page":1,"page_size":10,"total_pages":1}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/groups/search":{"post":{"tags":["Permissions"],"summary":"Search Groups","description":"Search groups in the authenticated user's organization.\n\nSupports filtering by:\n- **name**: Filter by group name (partial match)\n- **is_active**: Filter by group active status\n- **created_at**: Filter by creation date (YYYY-MM-DD)\n- **group_source**: Filter by group source (`MANUAL`, `SCIM`)\n\nResults are paginated and sortable by name, created_at, or updated_at.","operationId":"search_groups_v1_groups_search_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The page number to return","examples":[1],"default":1,"title":"Page"},"description":"The page number to return"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"The number of groups to return per page","examples":[10],"default":10,"title":"Page Size"},"description":"The number of groups to return per page"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort by field (name, created_at, updated_at)","examples":["created_at"],"default":"created_at","title":"Sort By"},"description":"Sort by field (name, created_at, updated_at)"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","description":"Sort order (asc or desc)","examples":["desc"],"default":"desc","title":"Sort Order"},"description":"Sort order (asc or desc)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchGroupsRequest"},"examples":{"by_name":{"summary":"Search groups by name","value":{"name":"Engineering"}},"active_groups":{"summary":"Search for active groups","value":{"is_active":true}},"by_source":{"summary":"Filter groups by source","value":{"group_source":"MANUAL"}}}}}},"responses":{"200":{"description":"Successfully searched groups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchGroupsResponse","description":"Response model for group search results.","properties":{"groups":{"description":"List of groups","items":{"$ref":"#/components/schemas/SearchGroupItem"},"title":"Groups","type":"array"},"metadata":{"$ref":"#/components/schemas/SearchGroupsMetadata","description":"Search metadata"}},"required":["groups","metadata"],"title":"SearchGroupsResponse","type":"object"},"examples":{"success":{"summary":"Successfully searched groups","value":{"groups":[{"id":"grp_001","name":"Engineering Team","is_active":true,"updated_at":"2024-08-15T10:30:00.000Z","created_at":"2024-07-29T15:51:28.071Z","member_count":12},{"id":"grp_002","name":"Design Team","is_active":true,"updated_at":"2024-08-10T08:00:00.000Z","created_at":"2024-06-01T09:00:00.000Z","member_count":5}],"metadata":{"total":2}}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/collections/{collection_id}/share":{"post":{"tags":["Permissions"],"summary":"Share Collection","description":"Share a collection with specified users, groups, and/or entire organization.\n\nSupports:\n- **Grant access**: Share with users, groups, or organizations by providing their IDs\n- **Revoke access**: Remove access for specific users, groups, or organizations\n- **Role assignment**: Assign roles (`owner`, `editor`, `reader`) when granting access\n\nThe response returns the updated list of all actors (users, groups, organizations)\nwith access to the collection.","operationId":"share_collection_v1_collections__collection_id__share_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","description":"Unique identifier of the collection to share","examples":["col_123abc456def"],"title":"Collection Id"},"description":"Unique identifier of the collection to share"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionShareRequest"},"examples":{"grant_to_users":{"summary":"Share collection with specific users","value":{"user_ids":["1001","1002"],"role":"editor","action":"grant"}},"grant_to_groups":{"summary":"Share collection with groups","value":{"group_ids":["501","502"],"role":"reader","action":"grant"}},"revoke_access":{"summary":"Revoke user access to collection","value":{"user_ids":["1001"],"action":"revoke"}}}}}},"responses":{"200":{"description":"Collection shared successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionActorsResponse","description":"Response model for collection actors.","properties":{"users":{"description":"List of users with access to the collection","items":{"anyOf":[{"$ref":"#/components/schemas/Actor"},{"$ref":"#/components/schemas/ActorWithStatus"}]},"title":"Users","type":"array"},"groups":{"description":"List of groups with access to the collection","items":{"anyOf":[{"$ref":"#/components/schemas/Actor"},{"$ref":"#/components/schemas/ActorWithStatus"}]},"title":"Groups","type":"array"}},"required":["users","groups"],"title":"CollectionActorsResponse","type":"object"},"examples":{"success":{"summary":"Successfully shared collection","value":{"users":[{"actor":{"id":"1001","name":"John Doe","role":"editor","avatar_url":"https://example.com/avatars/john.jpg"},"status":"Access granted."},{"actor":{"id":"1002","name":"Jane Smith","role":"editor"},"status":"Access granted."}],"groups":[{"actor":{"id":"501","name":"Engineering Team","role":"reader"},"status":"Access granted."}]}}}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/connectors/{connector_id}/activate":{"post":{"tags":["Connectors"],"summary":"Activate Connector","description":"Connect the authenticated user's account to a connector.\n\nUse this when a chat stream emits `tool_intervention_required` with `kind: activation`.\n\n- **OAuth connectors**: send an empty body. Open `authorization_url` in a popup. The popup\n  closes itself when the user finishes. Then check that `GET /v1/connectors/{connector_id}`\n  returns `status: ACTIVE`.\n- **API key or environment variable connectors**: send `auth_credentials`. The response is\n  `active` straight away.\n\nOnce the connector is `ACTIVE`, resolve the intervention with `activated`, or `canceled`\nif the user gave up.","operationId":"activate_connector_v1_connectors__connector_id__activate_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"connector_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Connector ID","examples":["linear_mcp"],"title":"Connector Id"},"description":"Connector ID"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorActivateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorActivateResponse"}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/connectors/{connector_id}":{"get":{"tags":["Connectors"],"summary":"Get Connector Status","description":"Get the connector's connection status for the authenticated user (`status: ACTIVE` when connected).","operationId":"get_connector_status_v1_connectors__connector_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"connector_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Connector ID","examples":["linear_mcp"],"title":"Connector Id"},"description":"Connector ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorStatus"}}}},"401":{"description":"Authentication failed - Invalid or missing credentials","content":{"application/json":{"example":{"detail":"Invalid or expired authentication token"}}}},"403":{"description":"Permission denied - Insufficient privileges","content":{"application/json":{"example":{"detail":"You don't have permission to access this resource"}}}},"404":{"description":"Resource not found","content":{"application/json":{"example":{"detail":"The requested resource was not found"}}}},"422":{"description":"Validation error - Invalid request data","content":{"application/json":{"example":{"detail":[{"loc":["body","agent_id"],"msg":"field required","type":"value_error.missing"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred"}}}}}}},"/v1/voice/voices":{"get":{"tags":["Voice"],"summary":"List Voice Capabilities","description":"Return the backend's provider-neutral mode and voice catalog.","operationId":"list_voices_v1_voice_voices_get","responses":{"200":{"description":"Available voice modes and public voice IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceCapabilitiesResponse","properties":{"version":{"type":"string","title":"Version"},"modes":{"items":{"$ref":"#/components/schemas/PublicVoiceMode"},"type":"array","title":"Modes"}},"additionalProperties":false,"type":"object","required":["version","modes"],"title":"VoiceCapabilitiesResponse"},"example":{"version":"2026-08-06","modes":[{"id":"en","name":"English","type":"single_language","supported_locales":["en-US"],"default_voice_id":"vc_mCZWm0DThaNgMwkU","voices":[{"id":"vc_mCZWm0DThaNgMwkU","name":"English voice","metadata":{}}]}]}}}},"400":{"description":"Invalid voice request","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"403":{"description":"Permission denied","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"409":{"description":"Session grant already used","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"413":{"description":"Request payload too large","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"415":{"description":"Unsupported audio format","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"422":{"description":"Unsupported mode, voice, or option","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"429":{"description":"Voice capacity exhausted","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"503":{"description":"Voice pipeline unavailable","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"504":{"description":"Voice upstream timeout","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}}},"security":[{"X-API-Key":[]}]}},"/v1/voice/voices/previews/{preview_id}":{"get":{"tags":["Voice"],"summary":"Get Voice Preview","operationId":"get_voice_preview_v1_voice_voices_previews__preview_id__get","security":[{"X-API-Key":[]}],"parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","title":"Preview Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Invalid voice request","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"403":{"description":"Permission denied","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"409":{"description":"Session grant already used","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"413":{"description":"Request payload too large","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"415":{"description":"Unsupported audio format","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"422":{"description":"Unsupported mode, voice, or option","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"429":{"description":"Voice capacity exhausted","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"503":{"description":"Voice pipeline unavailable","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"504":{"description":"Voice upstream timeout","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}}}}},"/v1/voice/text-to-speech":{"post":{"tags":["Voice"],"summary":"Synthesize Speech","description":"Synthesize text with a discovered mode and optional public voice ID.","operationId":"text_to_speech_v1_voice_text_to_speech_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextToSpeechRequest"},"examples":{"default_voice":{"summary":"Synthesize with the mode's default voice","value":{"text":"Hello from ASK.","mode_id":"en","response_format":"wav"}},"selected_voice":{"summary":"Synthesize with a discovered public voice ID","value":{"text":"Hello from ASK.","mode_id":"en","voice_id":"vc_mCZWm0DThaNgMwkU","response_format":"wav"}}}}},"required":true},"responses":{"200":{"description":"Synthesized audio","content":{"application/json":{"schema":{}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid voice request","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"403":{"description":"Permission denied","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"409":{"description":"Session grant already used","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"413":{"description":"Request payload too large","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"415":{"description":"Unsupported audio format","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"422":{"description":"Unsupported mode, voice, or option","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"429":{"description":"Voice capacity exhausted","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"503":{"description":"Voice pipeline unavailable","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"504":{"description":"Voice upstream timeout","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}}},"security":[{"X-API-Key":[]}]}},"/v1/voice/speech-to-text":{"post":{"tags":["Voice"],"summary":"Recognize Speech","description":"Transcribe one mono PCM16 WAV using the selected public voice mode.","operationId":"speech_to_text_v1_voice_speech_to_text_post","security":[{"X-API-Key":[]}],"parameters":[{"name":"mode_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Mode Id"}},{"name":"include_words","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Words"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_speech_to_text_v1_voice_speech_to_text_post"}}}},"responses":{"200":{"description":"One-shot speech recognition result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechToTextResponse","additionalProperties":false,"properties":{"text":{"title":"Text","type":"string"},"mode_id":{"title":"Mode Id","type":"string"},"words":{"anyOf":[{"items":{"$ref":"#/components/schemas/SpeechToTextWord"},"type":"array"},{"type":"null"}],"title":"Words"}},"required":["text","mode_id"],"title":"SpeechToTextResponse","type":"object"},"example":{"text":"Hello everyone.","mode_id":"en","words":[{"word":"Hello","start_s":0.0,"stop_s":0.35,"confidence":0.98},{"word":"everyone","start_s":0.36,"stop_s":0.9,"confidence":0.96}]}}}},"400":{"description":"Invalid voice request","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"403":{"description":"Permission denied","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"409":{"description":"Session grant already used","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"413":{"description":"Request payload too large","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"415":{"description":"Unsupported audio format","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"422":{"description":"Unsupported mode, voice, or option","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"429":{"description":"Voice capacity exhausted","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"503":{"description":"Voice pipeline unavailable","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"504":{"description":"Voice upstream timeout","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}}}}},"/v1/voice/sessions":{"post":{"tags":["Voice"],"summary":"Create Realtime Voice Session","description":"Create a one-use realtime grant using the assistant's saved voice settings.","operationId":"create_session_v1_voice_sessions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVoiceSessionRequest"},"examples":{"new_conversation":{"summary":"Start a voice session with an agent","value":{"agent_id":"0ab7c741-1aad-4965-84fb-e33c1524d953"}},"existing_conversation":{"summary":"Continue an existing conversation","value":{"agent_id":"0ab7c741-1aad-4965-84fb-e33c1524d953","conversation_id":"conversation_123"}}}}},"required":true},"responses":{"200":{"description":"Short-lived, one-use realtime session grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVoiceSessionResponse","properties":{"id":{"type":"string","title":"Id"},"websocket_url":{"type":"string","title":"Websocket Url"},"client_secret":{"$ref":"#/components/schemas/ClientSecret"},"configuration":{"$ref":"#/components/schemas/VoiceSessionConfiguration"}},"additionalProperties":false,"type":"object","required":["id","websocket_url","client_secret","configuration"],"title":"CreateVoiceSessionResponse"},"example":{"id":"voice_session_123","websocket_url":"wss://api.example/v1/voice/realtime","client_secret":{"value":"returned-once-secret","expires_at":"2026-08-04T12:00:30Z"},"configuration":{"mode_id":"en","voice_id":"vc_mCZWm0DThaNgMwkU","input_audio_format":"opus","output_audio_format":"opus","sample_rate_hz":24000,"channels":1}}}}},"400":{"description":"Invalid voice request","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"403":{"description":"Permission denied","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"409":{"description":"Session grant already used","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"413":{"description":"Request payload too large","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"415":{"description":"Unsupported audio format","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"422":{"description":"Unsupported mode, voice, or option","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"429":{"description":"Voice capacity exhausted","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"503":{"description":"Voice pipeline unavailable","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}},"504":{"description":"Voice upstream timeout","content":{"application/json":{"example":{"detail":{"reason":"invalid_voice_mode_selection","message":"The selected voice mode is not available."}}}}}},"security":[{"X-API-Key":[]}]}}},"components":{"schemas":{"Actor":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier of the actor","examples":["1001"]},"name":{"type":"string","title":"Name","description":"Display name of the actor","examples":["John Doe"]},"role":{"type":"string","title":"Role","description":"Role of the actor in the collection","examples":["editor"]},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"URL to the actor's avatar image","examples":["https://example.com/avatars/john.jpg"]}},"type":"object","required":["id","name","role"],"title":"Actor","description":"Model for collection actors (users, groups, organizations)."},"ActorWithStatus":{"properties":{"actor":{"$ref":"#/components/schemas/Actor","description":"Actor details"},"status":{"type":"string","title":"Status","description":"Status of the sharing action","examples":["Access granted."]}},"type":"object","required":["actor","status"],"title":"ActorWithStatus","description":"Model for collection actor with status information."},"AgentCreate":{"properties":{"use_all_collections":{"type":"boolean","title":"Use All Collections","description":"Whether agent has access to all collections. If true collection_ids is ignored","default":false,"examples":[false]},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"List of specific collection IDs to grant access to","default":[],"examples":[["col_123abc456def","col_789ghi012jkl"]]},"description":{"type":"string","title":"Description","description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"]},"settings":{"$ref":"#/components/schemas/AgentSettings","description":"Agent configuration settings"},"title":{"type":"string","title":"Title","description":"Display name for the agent","examples":["Customer Support Agent"]}},"type":"object","required":["settings","title"],"title":"AgentCreate"},"AgentCreatePatch":{"properties":{"use_all_collections":{"type":"boolean","title":"Use All Collections","description":"Whether agent has access to all collections. If true collection_ids is ignored","examples":[false]},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"List of specific collection IDs to grant access to","examples":[["col_123abc456def","col_789ghi012jkl"]]},"description":{"type":"string","title":"Description","description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"]},"settings":{"$ref":"#/components/schemas/AgentSettingsPatch","description":"Agent configuration settings"},"title":{"type":"string","title":"Title","description":"Display name for the agent","examples":["Customer Support Agent"]}},"type":"object","title":"AgentCreatePatch","description":"Model for patching an agent."},"AgentList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AgentRead"},"type":"array","title":"Data","description":"List of agents"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"AgentList","description":"Model for agent list response."},"AgentRead":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"]},"title":{"type":"string","title":"Title","description":"Display name of the agent","examples":["Customer Support Agent"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Brief description of the agent","examples":["An agent that helps with customer support queries"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Agent role in the system","examples":["assistant"]},"icon_details":{"anyOf":[{"$ref":"#/components/schemas/IconDetails"},{"type":"null"}],"description":"Icon details with color and icon identifier"},"llm_model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model Id","description":"Underlying LLM model used by the agent","examples":["anthropic/claude-sonnet-4"]},"created_by":{"anyOf":[{"$ref":"#/components/schemas/CreatedBy"},{"type":"null"}],"description":"Creator information"},"is_pinned":{"type":"boolean","title":"Is Pinned","description":"Whether the agent is pinned by the current user","default":false},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]}},"type":"object","required":["id","title","created_at"],"title":"AgentRead","description":"Model for reading agent data."},"AgentSettings":{"properties":{"creativity_level":{"$ref":"#/components/schemas/CreativityLevel","description":"Creativity level for agent responses:\n\n| Level | Description |\n|-------|-------------|\n| `deterministic` | For consistent, predictable outputs |\n| `creative` | Maximizes originality and imagination |\n| `factual` | Prioritizes accuracy and facts |\n| `balance` | Blends creativity and accuracy |","default":"deterministic","examples":["balance"]},"instruction":{"type":"string","title":"Instruction","description":"System instructions defining agent behavior","examples":["You are a helpful customer support agent. Be polite and professional."]},"llm_model":{"type":"string","title":"Llm Model","description":"Name of an inference model. Use GET /v1/agents/models to discover valid values.","examples":["Claude Sonnet 4"]}},"type":"object","required":["instruction","llm_model"],"title":"AgentSettings"},"AgentSettingsPatch":{"properties":{"creativity_level":{"$ref":"#/components/schemas/CreativityLevel","description":"Creativity level for agent responses","examples":["balance"]},"instruction":{"type":"string","title":"Instruction","description":"System instructions defining agent behavior","examples":["You are a helpful customer support agent. Be polite and professional."]},"llm_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llm Model","description":"Name of an inference model. Use GET /v1/agents/models to discover valid values.","examples":["Claude Sonnet 4"]}},"type":"object","title":"AgentSettingsPatch"},"AgentSort":{"type":"string","enum":["created_at","updated_at","title","recently_used"],"title":"AgentSort","description":"Enum for agent sorting options."},"AgentSortDirection":{"type":"string","enum":["asc","desc"],"title":"AgentSortDirection","description":"Enum for agent sort direction."},"Body_send_message_with_files_v1_conversations_with_uploads_post":{"properties":{"files":{"anyOf":[{"items":{"type":"string","format":"binary"},"type":"array"},{"type":"null"}],"title":"Files","description":"Files to upload and send with the message"},"query":{"type":"string","title":"Query","description":"User query or message content"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"Unique identifier of the agent"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name","description":"Name of the agent (alternative to agent_id)"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id","description":"Conversation ID to continue an existing conversation"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID for file uploads. If omitted, resolved from conversation or auto-created."},"stream":{"type":"boolean","title":"Stream","description":"Whether to stream the response using Server-Sent Events","default":false},"run_in_background":{"type":"boolean","title":"Run In Background","description":"Return HTTP 202 immediately and continue upload and message processing in the server request scope","default":false},"is_incognito":{"type":"boolean","title":"Is Incognito","description":"Whether the message is sent in incognito mode","default":true},"message_only":{"type":"boolean","title":"Message Only","description":"Whether to include only message content, excluding thoughts and steps","default":false},"bypass_tool_approval":{"type":"boolean","title":"Bypass Tool Approval","description":"Whether eligible tool approval requests are automatically approved. Set to false to require tool approval.","default":true},"user_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Context","description":"User context as a JSON string, e.g. `{\"context_mode\": \"custom\", \"custom_context\": {\"name\": \"John\"}}`"},"knowledge_base":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Knowledge Base","description":"Knowledge base collections as a JSON string, e.g. `{\"collections\": [{\"collection_id\": \"uuid\", \"document_ids\": [\"uuid\"]}]}`"}},"type":"object","required":["query"],"title":"Body_send_message_with_files_v1_conversations_with_uploads_post"},"Body_speech_to_text_v1_voice_speech_to_text_post":{"properties":{"file":{"type":"string","title":"File","description":"Mono PCM16 WAV.","format":"binary"}},"type":"object","required":["file"],"title":"Body_speech_to_text_v1_voice_speech_to_text_post"},"Body_update_document_v1_documents_patch":{"properties":{"file":{"anyOf":[{"type":"string","format":"binary"},{"type":"null"}],"title":"File","description":"New file to replace existing document content"},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name","description":"New filename for the document"},"metadata":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata","description":"Updated metadata as JSON string, e.g. {\"source\": \"updated\"}"}},"type":"object","title":"Body_update_document_v1_documents_patch"},"Body_upload_document_v1_documents_upload_post":{"properties":{"file":{"type":"string","title":"File","description":"File to upload","format":"binary"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID to upload the document to"},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name","description":"Collection name (used to resolve collection_id if not provided)"},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name","description":"Custom file name (optional)"},"metadata":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata","description":"Document metadata as JSON string, e.g. {\"source\": \"system\"}"}},"type":"object","required":["file"],"title":"Body_upload_document_v1_documents_upload_post"},"ClientSecret":{"properties":{"value":{"type":"string","title":"Value"},"expires_at":{"type":"string","title":"Expires At"}},"additionalProperties":false,"type":"object","required":["value","expires_at"],"title":"ClientSecret"},"CollectionActorsResponse":{"properties":{"users":{"items":{"anyOf":[{"$ref":"#/components/schemas/Actor"},{"$ref":"#/components/schemas/ActorWithStatus"}]},"type":"array","title":"Users","description":"List of users with access to the collection"},"groups":{"items":{"anyOf":[{"$ref":"#/components/schemas/Actor"},{"$ref":"#/components/schemas/ActorWithStatus"}]},"type":"array","title":"Groups","description":"List of groups with access to the collection"}},"type":"object","required":["users","groups"],"title":"CollectionActorsResponse","description":"Response model for collection actors."},"CollectionCreateRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","examples":["Project Documents"]},"description":{"type":"string","maxLength":500,"title":"Description","examples":["Collection of project documents"]},"is_hidden":{"type":"boolean","title":"Is Hidden","description":"Whether the collection is hidden","default":false}},"type":"object","required":["name"],"title":"CollectionCreateRequest","description":"Request model for creating a collection."},"CollectionDeleteRequest":{"properties":{"collection_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Collection Ids","description":"List of collection IDs to delete"}},"type":"object","required":["collection_ids"],"title":"CollectionDeleteRequest","description":"Request model for deleting collections."},"CollectionResponse":{"properties":{"id":{"type":"string","title":"Id","examples":["1"]},"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name","examples":["Project Documents"]},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","examples":["Collection of project documents"]},"is_hidden":{"type":"boolean","title":"Is Hidden","default":false},"organization_id":{"type":"string","title":"Organization Id","default":"0","examples":["101"]},"created_by":{"type":"string","title":"Created By","default":"0","examples":["1001"]},"document_count":{"type":"integer","title":"Document Count","description":"Count of active documents in the collection","examples":[5]},"data_source_types":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Data Source Types","examples":[["upload_file","google_drive"]]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Role of the current user on the collection","examples":["editor"]},"share_status":{"type":"string","title":"Share Status","description":"Indicates sharing status of the collection","default":"Private","examples":["Private"]},"created_at":{"type":"integer","title":"Created At","examples":[1739429535]},"updated_at":{"type":"integer","title":"Updated At","examples":[1739429535]},"is_deleted":{"type":"boolean","title":"Is Deleted","default":false,"examples":[false]}},"type":"object","required":["id","name","document_count","data_source_types","created_at","updated_at"],"title":"CollectionResponse","description":"Response model for collection operations."},"CollectionShareRequest":{"properties":{"user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"User Ids","description":"List of user IDs to share with","examples":[["1001","1002","1003"]]},"group_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Group Ids","description":"List of group IDs to share with","examples":[["501","502"]]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Role to grant to the shared entities","examples":[null,"owner","editor","reader"]},"action":{"type":"string","title":"Action","description":"Action to perform (grant or revoke access)","default":"grant","examples":["grant","revoke"]}},"type":"object","title":"CollectionShareRequest","description":"Request model for sharing collections."},"CollectionUpdate":{"properties":{"name":{"type":"string","title":"Name","description":"New name for the collection"},"description":{"type":"string","title":"Description","description":"New description for the collection"}},"type":"object","title":"CollectionUpdate","description":"Request model for updating a collection."},"ConnectorActivateRequest":{"properties":{"auth_credentials":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Auth Credentials","description":"Credentials for non-OAuth connectors: `{\"bearer_token\": \"...\"}` for API key connectors, or `{\"env_vars\": {...}}` for environment variable connectors.","examples":[{"bearer_token":"lin_api_..."}]}},"type":"object","title":"ConnectorActivateRequest","description":"Credentials for connectors that do not use OAuth. Send an empty body for OAuth."},"ConnectorActivateResponse":{"properties":{"connector_id":{"type":"string","title":"Connector Id","description":"Connector ID","examples":["linear_mcp"]},"status":{"type":"string","title":"Status","description":"`active` when connected, `requires_auth` when the user must finish OAuth, or `error`","examples":["requires_auth"]},"authorization_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization Url","description":"OAuth URL to open in a popup when `status` is `requires_auth`"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional context"}},"type":"object","required":["connector_id","status"],"title":"ConnectorActivateResponse","description":"Result of starting a connector activation."},"ConnectorStatus":{"properties":{"connector_id":{"type":"string","title":"Connector Id","description":"Connector ID","examples":["linear_mcp"]},"display_name":{"type":"string","title":"Display Name","description":"Human-readable connector name","examples":["Linear"]},"requires_auth":{"type":"boolean","title":"Requires Auth","description":"Whether the connector needs the user to authenticate"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`ACTIVE` once the user is connected. Other values: `PENDING_AUTH`, `AUTH_EXPIRED`, `INACTIVE`, `DISABLED`, `CONNECTION_FAILED`. Unlike the activate response, these are upper case.","examples":["ACTIVE"]},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Connector icon URL"}},"type":"object","required":["connector_id","display_name","requires_auth"],"title":"ConnectorStatus","description":"Connection status of a connector for the authenticated user."},"ConversationMessages":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Message"},"type":"array","title":"Data","description":"List of messages for conversation"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of messages"}},"type":"object","required":["data","pagination"],"title":"ConversationMessages"},"ConversationRead":{"properties":{"conversation_id":{"type":"string","title":"Conversation Id","description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"]},"name":{"type":"string","title":"Name","description":"Conversation name/title","examples":["Weather Discussion"]},"owner":{"type":"integer","title":"Owner","description":"Owner user ID","examples":[334067997469574321]},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Associated collection ID for document context","examples":["col_123abc456def"]},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]},"updated_at":{"type":"string","title":"Updated At","description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]},"is_enabled":{"type":"boolean","title":"Is Enabled","description":"Whether the conversation is currently enabled","examples":[true]},"is_incognito":{"type":"boolean","title":"Is Incognito","description":"Whether the conversation is in incognito/private mode","examples":[false]},"last_activity":{"type":"string","title":"Last Activity","description":"Last activity timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]}},"type":"object","required":["conversation_id","name","owner","created_at","updated_at","is_enabled","is_incognito","last_activity"],"title":"ConversationRead","description":"Model for reading conversation data."},"Conversations":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ConversationRead"},"type":"array","title":"Data","description":"List of conversations"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination information"}},"type":"object","required":["data","pagination"],"title":"Conversations","description":"Model for conversations list response."},"CreateVoiceSessionRequest":{"properties":{"agent_id":{"type":"string","minLength":1,"title":"Agent Id"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id"}},"additionalProperties":false,"type":"object","required":["agent_id"],"title":"CreateVoiceSessionRequest"},"CreateVoiceSessionResponse":{"properties":{"id":{"type":"string","title":"Id"},"websocket_url":{"type":"string","title":"Websocket Url"},"client_secret":{"$ref":"#/components/schemas/ClientSecret"},"configuration":{"$ref":"#/components/schemas/VoiceSessionConfiguration"}},"additionalProperties":false,"type":"object","required":["id","websocket_url","client_secret","configuration"],"title":"CreateVoiceSessionResponse"},"CreatedBy":{"properties":{"id":{"type":"string","title":"Id","description":"User ID of the creator"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name of the creator"}},"type":"object","required":["id"],"title":"CreatedBy","description":"Model for agent creator information."},"CreativityLevel":{"type":"string","enum":["deterministic","creative","factual","balance"],"title":"CreativityLevel"},"DocumentCancelProcessingRequest":{"properties":{"document_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Document Ids","description":"List of document IDs to cancel"}},"type":"object","required":["document_ids"],"title":"DocumentCancelProcessingRequest","description":"Request model for canceling document processing."},"DocumentProcessingResponse":{"properties":{"processed_documents":{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array","title":"Processed Documents","description":"List of processed documents with their details."},"skipped_documents":{"items":{"$ref":"#/components/schemas/SkippedDocument"},"type":"array","title":"Skipped Documents","description":"List of skipped documents, each with a 'document_id' and a 'reason' (e.g., document not found, already processed, invalid state)."}},"type":"object","title":"DocumentProcessingResponse","description":"Response model for bulk document processing/operations (retry/cancel)."},"DocumentProcessingStatus":{"type":"string","enum":["uploading","failed","failed and cannot retry","queued","processing","ready","cancelled","upload_failed","upload_failed_duplicate_content","upload_failed_not_supported"],"title":"DocumentProcessingStatus","description":"Enum for document processing status."},"DocumentResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Document ID"},"filename":{"type":"string","title":"Filename","default":"","examples":["document.pdf"]},"file_type":{"type":"string","title":"File Type","default":"","examples":["pdf"]},"file_size":{"type":"integer","title":"File Size","default":0,"examples":[204800]},"data_source_type":{"type":"string","title":"Data Source Type","default":"upload_file","examples":["google_drive"]},"processing_status":{"type":"string","title":"Processing Status","default":"uploading","examples":["queued"]},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id","description":"Collection ID"},"file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Hash","examples":["hash-value"]},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata","examples":[null,{"category":"finance","source":"user"}]},"owner_id":{"type":"string","title":"Owner Id","default":"0","examples":["1001"]},"created_at":{"type":"integer","title":"Created At","description":"Creation timestamp"},"updated_at":{"type":"integer","title":"Updated At","description":"Last update timestamp"},"is_deleted":{"type":"boolean","title":"Is Deleted","default":false,"examples":[false]}},"type":"object","required":["id","created_at","updated_at"],"title":"DocumentResponse","description":"Response model for document operations."},"DocumentRetryProcessingRequest":{"properties":{"document_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Document Ids","description":"List of document IDs to retry"}},"type":"object","required":["document_ids"],"title":"DocumentRetryProcessingRequest","description":"Request model for retrying document processing."},"DocumentUploadResponse":{"properties":{"status":{"type":"string","title":"Status","examples":["uploading"]},"document_name":{"type":"string","title":"Document Name","default":"","examples":["document.pdf"]},"file_hash":{"type":"string","title":"File Hash","default":"","examples":["hash-value"]},"body":{"anyOf":[{"$ref":"#/components/schemas/SuccessDocumentUploadResponse"},{"$ref":"#/components/schemas/FailedDocumentUploadInitiateResponse"}],"title":"Body","description":"document details"}},"type":"object","required":["status","body"],"title":"DocumentUploadResponse","description":"Response model for document upload."},"FailedDocumentUploadInitiateResponse":{"properties":{"error_message":{"type":"string","title":"Error Message","examples":["error message"]}},"type":"object","required":["error_message"],"title":"FailedDocumentUploadInitiateResponse","description":"Failed response for document upload initiation."},"Feedback":{"properties":{"sources":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sources","description":"List of source URLs or references","examples":[["https://weather.com/tokyo","https://example.com/source"]]},"vote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote","description":"User vote (e.g., UPVOTE, DOWNVOTE)","examples":["UPVOTE"]}},"type":"object","title":"Feedback"},"IconDetails":{"properties":{"color":{"type":"string","title":"Color","description":"Icon color identifier","default":"agent1","examples":["agent1"]},"icon":{"type":"string","title":"Icon","description":"Icon name identifier","default":"brain","examples":["brain"]}},"type":"object","title":"IconDetails"},"KnowledgeBase":{"properties":{"collections":{"anyOf":[{"items":{"$ref":"#/components/schemas/KnowledgeBaseCollection"},"type":"array"},{"type":"null"}],"title":"Collections","description":"List of collections with their associated documents"}},"type":"object","title":"KnowledgeBase","description":"Knowledge base collections and documents attached to a message."},"KnowledgeBaseCollection":{"properties":{"collection_id":{"type":"string","title":"Collection Id","description":"UUID of the collection","examples":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]},"document_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Document Ids","description":"Optional list of specific document UUIDs within the collection. When omitted, all documents in the collection are used.","examples":[["d1e2f3a4-b5c6-7890-abcd-ef1234567890"]]}},"type":"object","required":["collection_id"],"title":"KnowledgeBaseCollection","description":"A single collection reference for knowledge base."},"Message":{"properties":{"conversation_id":{"type":"string","title":"Conversation Id","description":"Unique identifier of the conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"]},"message_id":{"type":"string","title":"Message Id","description":"Unique identifier of the message","examples":["ae0acbe8-ec77-4231-911a-2fdd20d9dcbb"]},"parent_message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Message Id","description":"Parent message ID for threaded conversations","examples":["msg_parent_123"]},"sender_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Type","description":"Type of sender (e.g., user, agent)","examples":["agent"]},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"]},"message":{"type":"string","title":"Message","description":"Message content","examples":["The weather in Tokyo is currently 22°C."]},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the message has been deleted","examples":[false]},"feedback":{"anyOf":[{"$ref":"#/components/schemas/Feedback"},{"type":"null"}],"description":"User feedback on the message"},"thoughts":{"title":"Thoughts","description":"Agent's reasoning and thought process"},"steps":{"anyOf":[{"items":{"$ref":"#/components/schemas/StepItem"},"type":"array"},{"type":"null"}],"title":"Steps","description":"List of steps taken by the agent"},"agent_name":{"type":"string","title":"Agent Name","description":"Name of the agent","examples":["web-searcher"]},"uploads":{"anyOf":[{"items":{"$ref":"#/components/schemas/UploadItem"},"type":"array"},{"type":"null"}],"title":"Uploads","description":"Files and images uploaded with the message"}},"type":"object","required":["conversation_id","message_id","message","created_at","is_deleted"],"title":"Message","description":"Model for a message in a conversation."},"MessageCreate":{"properties":{"conversation_id":{"type":"string","title":"Conversation Id","description":"Conversation ID to continue an existing conversation","examples":["c4b12a3e-a456-7890-d12e-1fdd20d9dcbb"]},"agent_id":{"type":"string","title":"Agent Id","description":"Unique identifier of the agent to send the message to","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"]},"agent_name":{"type":"string","title":"Agent Name","description":"Name of the agent","examples":["web-searcher"]},"query":{"type":"string","title":"Query","description":"User query or message content","examples":["What is the weather in Tokyo?"]},"stream":{"type":"boolean","title":"Stream","description":"Whether to stream the response using Server-Sent Events","default":false,"examples":[false]},"run_in_background":{"type":"boolean","title":"Run In Background","description":"Return HTTP 202 immediately and continue processing the message in the server request scope. The result is not returned to the caller.","default":false,"examples":[false]},"collection_id":{"type":"string","title":"Collection Id","description":"Collection ID of documents referenced in uploads","examples":["col_123abc456def"]},"is_incognito":{"type":"boolean","title":"Is Incognito","description":"Whether the message is sent in incognito mode (not saved to history)","default":true,"examples":[false]},"message_only":{"type":"boolean","title":"Message Only","description":"Whether to include only message content, excluding thoughts and steps","default":false,"examples":[false]},"bypass_tool_approval":{"type":"boolean","title":"Bypass Tool Approval","description":"Whether eligible tool approval requests are automatically approved. Set to `false` to receive `tool_intervention_required` streaming events and resolve them through the tool interventions endpoint.","default":true,"examples":[true]},"uploads":{"items":{"$ref":"#/components/schemas/MessageUploadItem"},"type":"array","title":"Uploads","description":"List of file upload metadata for live file uploads. Each item references a file already uploaded to KMS by its document ID."},"user_context":{"$ref":"#/components/schemas/UserContext","description":"User context","default":{"context_mode":"none"}},"knowledge_base":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBase"},{"type":"null"}],"description":"Optional knowledge base collections and documents for this message. Allows attaching specific collections (and optionally specific documents within them) as context."}},"type":"object","required":["query"],"title":"MessageCreate","description":"Schema for creating a new message."},"MessageUploadItem":{"properties":{"file_document_id":{"type":"string","title":"File Document Id","description":"Document ID from KMS after file has been uploaded","examples":["doc_123abc456def"]},"file_name":{"type":"string","title":"File Name","description":"Name of the uploaded file","examples":["report.pdf"]},"upload_type":{"type":"string","enum":["file","image"],"title":"Upload Type","description":"Type of upload: `file` for documents or `image` for images","default":"file","examples":["file"]}},"type":"object","required":["file_document_id","file_name"],"title":"MessageUploadItem","description":"Upload metadata for live file uploads sent with a message.\n\nFor the live file upload flow, only document metadata is needed —\nno file content or base64 data is sent."},"ModelInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Canonical model ID"},"name":{"type":"string","title":"Name","description":"Human-readable model name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Model description"},"supported_languages":{"items":{"type":"string"},"type":"array","title":"Supported Languages","description":"Supported languages"},"is_default":{"type":"boolean","title":"Is Default","description":"Whether this is the organization's default model","default":false}},"type":"object","required":["id","name"],"title":"ModelInfo","description":"An inference model available to the authenticated organization."},"PaginatedCollectionResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CollectionResponse"},"type":"array","title":"Data","description":"List of collections"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of collections"}},"type":"object","required":["data","pagination"],"title":"PaginatedCollectionResponse","description":"Paginated response for collection list."},"PaginatedDocumentResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DocumentResponse"},"type":"array","title":"Data","description":"List of documents"},"pagination":{"$ref":"#/components/schemas/Pagination","description":"Pagination details for the list of documents"}},"type":"object","required":["data","pagination"],"title":"PaginatedDocumentResponse","description":"Paginated response for document list."},"Pagination":{"properties":{"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of items per page"},"total_records":{"type":"integer","title":"Total Records","description":"Total number of records"},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages"}},"type":"object","required":["page","page_size","total_records","total_pages"],"title":"Pagination","description":"Model for pagination information."},"PublicVoice":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"preview":{"anyOf":[{"$ref":"#/components/schemas/PublicVoicePreview"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"PublicVoice"},"PublicVoiceMode":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["single_language","multilingual"],"title":"Type"},"supported_locales":{"items":{"type":"string"},"type":"array","title":"Supported Locales"},"default_voice_id":{"type":"string","title":"Default Voice Id"},"voices":{"items":{"$ref":"#/components/schemas/PublicVoice"},"type":"array","title":"Voices"}},"additionalProperties":false,"type":"object","required":["id","name","type","supported_locales","default_voice_id","voices"],"title":"PublicVoiceMode"},"PublicVoicePreview":{"properties":{"id":{"type":"string","title":"Id"},"content_type":{"type":"string","const":"audio/wav","title":"Content Type","default":"audio/wav"}},"additionalProperties":false,"type":"object","required":["id"],"title":"PublicVoicePreview"},"SearchGroupItem":{"properties":{"id":{"type":"string","title":"Id","description":"Group ID"},"name":{"type":"string","title":"Name","description":"Group name"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the group is active"},"updated_at":{"type":"string","title":"Updated At","description":"Last update timestamp"},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp"},"member_count":{"type":"integer","title":"Member Count","description":"Number of members in the group"}},"type":"object","required":["id","name","is_active","updated_at","created_at","member_count"],"title":"SearchGroupItem","description":"Single group item in the search results."},"SearchGroupsMetadata":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of groups"}},"type":"object","required":["total"],"title":"SearchGroupsMetadata","description":"Metadata for group search results."},"SearchGroupsRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Name","description":"The name of the group to search for","examples":["Engineering Team"]},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Whether the group is active","examples":[true]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"Filter by creation date (YYYY-MM-DD format)","examples":["2024-07-29"]},"group_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Source","description":"The source of the group (MANUAL, SCIM)","examples":["MANUAL"]}},"type":"object","title":"SearchGroupsRequest","description":"Request body model for searching groups in an organization."},"SearchGroupsResponse":{"properties":{"groups":{"items":{"$ref":"#/components/schemas/SearchGroupItem"},"type":"array","title":"Groups","description":"List of groups"},"metadata":{"$ref":"#/components/schemas/SearchGroupsMetadata","description":"Search metadata"}},"type":"object","required":["groups","metadata"],"title":"SearchGroupsResponse","description":"Response model for group search results."},"SearchUserItem":{"properties":{"id":{"type":"string","title":"Id","description":"User ID"},"userState":{"type":"string","title":"Userstate","description":"User state"},"email":{"type":"string","title":"Email","description":"User email"},"firstName":{"type":"string","title":"Firstname","description":"User first name"},"lastName":{"type":"string","title":"Lastname","description":"User last name"},"displayName":{"type":"string","title":"Displayname","description":"User display name"},"phoneNumber":{"type":"string","title":"Phonenumber","description":"User phone number"},"isEmailVerified":{"type":"boolean","title":"Isemailverified","description":"Whether user email is verified"},"isPhoneVerified":{"type":"boolean","title":"Isphoneverified","description":"Whether user phone is verified"},"roles":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Roles","description":"List of user roles"},"creationDate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Creationdate","description":"User creation date","examples":["2024-07-29T15:51:28.071Z"]}},"type":"object","required":["id","userState","email","firstName","lastName","displayName","phoneNumber","isEmailVerified","isPhoneVerified"],"title":"SearchUserItem","description":"Single user item in the search results."},"SearchUsersMetadata":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of users","default":0},"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of users per page"},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages"}},"type":"object","required":["page","page_size","total_pages"],"title":"SearchUsersMetadata","description":"Metadata for user search results pagination."},"SearchUsersRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Name","description":"Filter by user name","examples":["John Doe"]},"email":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Email","description":"Filter by user email address","examples":["john.doe@example.com"]},"emails":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Emails","description":"Filter by a list of email addresses","examples":[["john.doe@example.com"]]},"user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"User Ids","description":"Filter by a list of user IDs","examples":[["1234567890"]]},"role_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role Name","description":"Filter by organization role (ask71_admin, organization_admin, member)","examples":["member"]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Filter by user status (ACTIVE, INACTIVE, INITIAL, LOCKED, DELETED)","examples":["ACTIVE"]},"email_or_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Or Name","description":"Filter by email or name (partial match)","examples":["John"]}},"type":"object","title":"SearchUsersRequest","description":"Request body model for searching users in an organization."},"SearchUsersResponse":{"properties":{"users":{"items":{"$ref":"#/components/schemas/SearchUserItem"},"type":"array","title":"Users","description":"List of users"},"metadata":{"$ref":"#/components/schemas/SearchUsersMetadata","description":"Pagination metadata"}},"type":"object","required":["metadata"],"title":"SearchUsersResponse","description":"Response model for user search results."},"SettingsRead":{"properties":{"creativity_level":{"type":"string","title":"Creativity Level","description":"Creativity level for agent responses","examples":["balance"]},"instruction":{"type":"string","title":"Instruction","description":"System instructions defining agent behavior","examples":["You are a helpful customer support agent. Be polite and professional."]},"llm_model":{"type":"string","title":"Llm Model","description":"Canonical ID of the inference model used by the agent","examples":["anthropic/claude-sonnet-4"]}},"type":"object","required":["creativity_level","instruction","llm_model"],"title":"SettingsRead"},"SingleAgentRead":{"properties":{"id":{"type":"string","title":"Id","description":"Unique identifier of the agent","examples":["0e546d24-09a3-41f7-9a2f-11a8bbc2160e"]},"use_all_collections":{"type":"boolean","title":"Use All Collections","description":"Whether agent has access to all collections. If true collection_ids is ignored.","examples":[false]},"collection_ids":{"items":{"type":"string"},"type":"array","title":"Collection Ids","description":"List of specific collection IDs accessible to agent","examples":[["col_123abc456def","col_789ghi012jkl"]]},"created_at":{"type":"string","title":"Created At","description":"Creation timestamp in ISO 8601 format","examples":["2025-10-10T08:44:27.781137Z"]},"created_by":{"type":"integer","title":"Created By","description":"User ID of the creator","examples":[1001]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Brief description of the agent's purpose","examples":["An agent that helps with customer support queries"]},"is_deleted":{"type":"boolean","title":"Is Deleted","description":"Whether the agent has been deleted","examples":[false]},"org_id":{"type":"integer","title":"Org Id","description":"Organization ID the agent belongs to","examples":[101]},"settings":{"$ref":"#/components/schemas/SettingsRead","description":"Agent configuration settings"},"title":{"type":"string","title":"Title","description":"Display name of the agent","examples":["Customer Support Agent"]},"updated_at":{"type":"string","title":"Updated At","description":"Last update timestamp in ISO 8601 format","examples":["2025-10-10T10:30:15.123456Z"]}},"type":"object","required":["id","use_all_collections","created_at","created_by","is_deleted","org_id","settings","title","updated_at"],"title":"SingleAgentRead"},"SkippedDocument":{"properties":{"document_id":{"type":"string","title":"Document Id","examples":["document-uuid"]},"reason":{"type":"string","title":"Reason","examples":["reason"]}},"type":"object","required":["document_id","reason"],"title":"SkippedDocument","description":"Response model for skipped document."},"SpeechToTextResponse":{"properties":{"text":{"type":"string","title":"Text"},"mode_id":{"type":"string","title":"Mode Id"},"words":{"anyOf":[{"items":{"$ref":"#/components/schemas/SpeechToTextWord"},"type":"array"},{"type":"null"}],"title":"Words"}},"additionalProperties":false,"type":"object","required":["text","mode_id"],"title":"SpeechToTextResponse"},"SpeechToTextWord":{"properties":{"word":{"type":"string","title":"Word"},"start_s":{"type":"number","title":"Start S"},"stop_s":{"type":"number","title":"Stop S"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"}},"additionalProperties":false,"type":"object","required":["word","start_s","stop_s"],"title":"SpeechToTextWord"},"StepItem":{"properties":{},"additionalProperties":true,"type":"object","title":"StepItem"},"SuccessDocumentUploadResponse":{"properties":{"document_id":{"type":"string","title":"Document Id","examples":["document-uuid"]}},"type":"object","required":["document_id"],"title":"SuccessDocumentUploadResponse","description":"Success response for document upload."},"TextToSpeechRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text"},"mode_id":{"type":"string","minLength":1,"title":"Mode Id"},"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Id"},"response_format":{"type":"string","enum":["wav","pcm"],"title":"Response Format","default":"wav"}},"additionalProperties":false,"type":"object","required":["text","mode_id"],"title":"TextToSpeechRequest"},"ToolApprovalRequest":{"properties":{"kind":{"type":"string","enum":["approval","activation"],"title":"Kind","description":"Tool intervention type, from the `tool_intervention_required` event. `approval` resolves with `approved`, `denied`, or `always_allow`. `activation` (connect a connector) resolves with `activated` or `canceled`.","default":"approval","examples":["approval"]},"resolutions":{"additionalProperties":{"type":"string"},"type":"object","minProperties":1,"title":"Resolutions","description":"Map of tool call IDs from the `tool_intervention_required` event to their resolution: `approved`, `denied`, or `always_allow` for `approval`; `activated` or `canceled` for `activation`.","examples":[{"tool_abc123":"approved"}]}},"type":"object","required":["resolutions"],"title":"ToolApprovalRequest","description":"Approval resolutions for tool calls waiting on user input."},"UploadItem":{"properties":{"upload_type":{"type":"string","title":"Upload Type","description":"Type of upload (e.g., file, image)","examples":["file"]},"base64_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Base64 Image","description":"Base64-encoded image data","examples":["data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."]},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name","description":"Name of the uploaded file","examples":["document.pdf"]},"file_content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Content","description":"Content of the uploaded file","examples":["This is the file content..."]},"file_document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Document Id","description":"Document ID for the uploaded file","examples":["doc_123abc456def"]}},"type":"object","required":["upload_type"],"title":"UploadItem","description":"Model for an upload item in a message response."},"UserContext":{"properties":{"custom_context":{"additionalProperties":true,"type":"object","title":"Custom Context","description":"Custom context","examples":[{"likes":"cricket","name":"allen"}]},"context_mode":{"type":"string","enum":["auto","custom","none"],"title":"Context Mode","description":"Context mode for user data:\n\n| Mode | Description |\n|------|-------------|\n| `auto` | Automatically passes user profile data (i.e. current_weekday, timezone, location, user_email, user_id, user_full_name). Can be overridden or extended using `custom_context`. |\n| `custom` | Only passes data from `custom_context` (e.g., `{'name': 'allen', 'likes': 'cricket'}`) |\n| `none` | No user context is passed to the agent |\n\n**Fields that can be overridden for `auto` mode:** user_time_zone, user_date_time, user_location, user_email, user_id, user_full_name","default":"none","examples":["none"]}},"type":"object","title":"UserContext","description":"Model for user context information."},"VoiceCapabilitiesResponse":{"properties":{"version":{"type":"string","title":"Version"},"modes":{"items":{"$ref":"#/components/schemas/PublicVoiceMode"},"type":"array","title":"Modes"}},"additionalProperties":false,"type":"object","required":["version","modes"],"title":"VoiceCapabilitiesResponse"},"VoiceSessionConfiguration":{"properties":{"mode_id":{"type":"string","title":"Mode Id"},"voice_id":{"type":"string","title":"Voice Id"},"input_audio_format":{"type":"string","title":"Input Audio Format","default":"opus"},"output_audio_format":{"type":"string","title":"Output Audio Format","default":"opus"},"sample_rate_hz":{"type":"integer","title":"Sample Rate Hz","default":24000},"channels":{"type":"integer","title":"Channels","default":1}},"additionalProperties":false,"type":"object","required":["mode_id","voice_id"],"title":"VoiceSessionConfiguration"}},"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"Provide your API Key in this header for authentication. Required for all endpoints. Example: 'x-api-key: <your-api-key>'.","in":"header","name":"x-api-key"}}}}