> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Detect Intent > Detect user intent from natural language request. This endpoint analyzes a user's request to determine whether they want to: - Execute queries on existing data (execution mode) - Create new resources/infrastructure (setup mode) - Or if the request is ambiguous and needs clarification It performs keyword analysis and checks existing collections to provide intelligent classification and recommendations. Args: request: FastAPI request with tenant context payload: Intent detection request with user's input Returns: IntentClassification with detected intent and recommendations Example: ```bash curl -X POST http://localhost:8000/v1/agents/intent/detect \ -H "Authorization: Bearer {api_key}" \ -H "X-Namespace: {namespace_id}" \ -H "Content-Type: application/json" \ -d '{ "user_request": "I want to search videos by faces", "include_collection_analysis": true }' ``` ## OpenAPI ````yaml post /v1/agents/sessions/intent/detect openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/agents/sessions/intent/detect: post: tags: - Agent Sessions summary: Detect Intent description: >- Detect user intent from natural language request. This endpoint analyzes a user's request to determine whether they want to: - Execute queries on existing data (execution mode) - Create new resources/infrastructure (setup mode) - Or if the request is ambiguous and needs clarification It performs keyword analysis and checks existing collections to provide intelligent classification and recommendations. Args: request: FastAPI request with tenant context payload: Intent detection request with user's input Returns: IntentClassification with detected intent and recommendations Example: ```bash curl -X POST http://localhost:8000/v1/agents/intent/detect \ -H "Authorization: Bearer {api_key}" \ -H "X-Namespace: {namespace_id}" \ -H "Content-Type: application/json" \ -d '{ "user_request": "I want to search videos by faces", "include_collection_analysis": true }' ``` operationId: detect_intent_v1_agents_sessions_intent_detect_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DetectIntentRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/IntentClassification' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: DetectIntentRequest: properties: user_request: type: string title: User Request description: User's natural language request include_collection_analysis: type: boolean title: Include Collection Analysis description: Whether to check existing collections default: true type: object required: - user_request title: DetectIntentRequest description: |- Request to detect intent from user input. Attributes: user_request: The user's natural language request to analyze include_collection_analysis: Whether to analyze existing collections IntentClassification: properties: intent: type: string pattern: ^(execution|setup|ambiguous)$ title: Intent description: 'Detected intent: ''execution'', ''setup'', or ''ambiguous''' confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Confidence in classification reasoning: type: string title: Reasoning description: Why this intent was detected suitable_collections: items: $ref: '#/components/schemas/SuitableCollection' type: array title: Suitable Collections description: Existing collections that might help recommended_action: type: string title: Recommended Action description: Next action to take (e.g., 'setup_pipeline', 'execute_retriever') clarification_needed: type: boolean title: Clarification Needed description: Whether to ask user for clarification clarification_options: items: $ref: '#/components/schemas/ClarificationOption' type: array title: Clarification Options description: Options for user if clarification needed keywords_found: additionalProperties: items: type: string type: array type: object title: Keywords Found description: >- Keywords found (setup_keywords, execution_keywords, neutral_keywords) type: object required: - intent - confidence - reasoning - recommended_action - clarification_needed title: IntentClassification description: >- Result of intent detection analysis. This model represents the agent's understanding of whether the user wants to: - Execute queries on existing data (execution mode) - Create new resources/infrastructure (setup mode) - Or if the request is ambiguous and needs clarification Attributes: intent: The detected intent ("execution", "setup", or "ambiguous") confidence: Confidence score 0.0-1.0 reasoning: Explanation of why this intent was detected suitable_collections: Existing collections that might fulfill the request recommended_action: What the agent should do next clarification_needed: Whether to ask user for clarification clarification_options: Options to present if clarification needed keywords_found: Keywords that influenced the classification ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SuitableCollection: properties: collection_id: type: string title: Collection Id description: Collection ID collection_name: type: string title: Collection Name description: Collection name feature_extractor: type: string title: Feature Extractor description: Feature extractor name capabilities: items: type: string type: array title: Capabilities description: Collection capabilities match_score: type: number maximum: 1 minimum: 0 title: Match Score description: Match confidence type: object required: - collection_id - collection_name - feature_extractor - match_score title: SuitableCollection description: |- Information about a collection that might fulfill the user's request. Attributes: collection_id: Collection identifier collection_name: Human-readable collection name feature_extractor: Extractor used in this collection capabilities: What this collection can do (e.g., "video search", "face detection") match_score: How well this collection matches the request (0.0-1.0) ClarificationOption: properties: label: type: string title: Label description: Option label description: type: string title: Description description: Option description action: type: string title: Action description: Recommended action/tool type: object required: - label - description - action title: ClarificationOption description: |- A single option presented to the user for clarifying intent. Attributes: label: Short label for the option (e.g., "Search existing data") description: Detailed explanation of what this option means action: Recommended tool/action to use if user selects this option ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````