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:

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

POST /v1/agents/sessions/intent/detect

Detect Intent

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/agents/sessions/intent/detect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "user_request": "<string>",
  "include_collection_analysis": true
}
'

200

{
  "intent": "<string>",
  "confidence": 0.5,
  "reasoning": "<string>",
  "recommended_action": "<string>",
  "clarification_needed": true,
  "suitable_collections": [
    {
      "collection_id": "<string>",
      "collection_name": "<string>",
      "feature_extractor": "<string>",
      "match_score": 0.5,
      "capabilities": [
        "<string>"
      ]
    }
  ],
  "clarification_options": [
    {
      "label": "<string>",
      "description": "<string>",
      "action": "<string>"
    }
  ],
  "keywords_found": {}
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

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 · default: true

Whether to check existing collections

Response

200

application/json

Successful Response

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'

Pattern: ^(execution|setup|ambiguous)$

confidence · number · required

Confidence in classification

Required range: 0 <= x <= 1

reasoning · string · required

Why this intent was detected

recommended_action · string · required

Next action to take (e.g., 'setup_pipeline', 'execute_retriever')

clarification_needed · boolean · required

Whether to ask user for clarification

suitable_collections · SuitableCollection · object[]

Existing collections that might help

Show child attributes

clarification_options · ClarificationOption · object[]

Options for user if clarification needed

Show child attributes

keywords_found · Keywords Found · object

Keywords found (setup_keywords, execution_keywords, neutral_keywords)

Show child attributes