Skip to main content
POST
/
v1
/
agents
/
sessions
/
intent
/
detect
Detect Intent
curl --request POST \
  --url https://api.mixpeek.com/v1/agents/sessions/intent/detect \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_request": "<string>",
  "include_collection_analysis": true
}
'
{
  "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": {}
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
authorization
string
​
X-Namespace
string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

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

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

​
clarification_options
ClarificationOption · object[]

Options for user if clarification needed

​
keywords_found
Keywords Found · object

Keywords found (setup_keywords, execution_keywords, neutral_keywords)