---
title: "Detect Intent"
method: POST
path: "/v1/agents/sessions/intent/detect"
tags: ["Agent Sessions"]
---

# Detect Intent

`POST /v1/agents/sessions/intent/detect`

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
      }'
    ```

## Request body

- DetectIntentRequest — 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
  - `user_request` string, required — User's natural language request
  - `include_collection_analysis` boolean — Whether to check existing collections

## Response `200`

Successful Response

- IntentClassification — 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
  - `intent` string, required — Detected intent: 'execution', 'setup', or 'ambiguous'
  - `confidence` number, required — Confidence in classification
  - `reasoning` string, required — Why this intent was detected
  - `suitable_collections` SuitableCollection[] — Existing collections that might help
    - `collection_id` string, required — Collection ID
    - `collection_name` string, required — Collection name
    - `feature_extractor` string, required — Feature extractor name
    - `capabilities` string[] — Collection capabilities
    - `match_score` number, required — Match confidence
  - `recommended_action` string, required — Next action to take (e.g., 'setup_pipeline', 'execute_retriever')
  - `clarification_needed` boolean, required — Whether to ask user for clarification
  - `clarification_options` ClarificationOption[] — Options for user if clarification needed
    - `label` string, required — Option label
    - `description` string, required — Option description
    - `action` string, required — Recommended action/tool
  - `keywords_found` object — Keywords found (setup_keywords, execution_keywords, neutral_keywords)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)