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
}
'import requests
url = "https://api.mixpeek.com/v1/agents/sessions/intent/detect"
payload = {
"user_request": "<string>",
"include_collection_analysis": True
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({user_request: '<string>', include_collection_analysis: true})
};
fetch('https://api.mixpeek.com/v1/agents/sessions/intent/detect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/agents/sessions/intent/detect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_request' => '<string>',
'include_collection_analysis' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/agents/sessions/intent/detect"
payload := strings.NewReader("{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/agents/sessions/intent/detect")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/agents/sessions/intent/detect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}"
response = http.request(request)
puts response.read_body{
"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": {}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}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
}'
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
}
'import requests
url = "https://api.mixpeek.com/v1/agents/sessions/intent/detect"
payload = {
"user_request": "<string>",
"include_collection_analysis": True
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({user_request: '<string>', include_collection_analysis: true})
};
fetch('https://api.mixpeek.com/v1/agents/sessions/intent/detect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/agents/sessions/intent/detect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_request' => '<string>',
'include_collection_analysis' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/agents/sessions/intent/detect"
payload := strings.NewReader("{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/agents/sessions/intent/detect")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/agents/sessions/intent/detect")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_request\": \"<string>\",\n \"include_collection_analysis\": true\n}"
response = http.request(request)
puts response.read_body{
"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": {}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
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.
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
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
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
Detected intent: 'execution', 'setup', or 'ambiguous'
^(execution|setup|ambiguous)$Confidence in classification
0 <= x <= 1Why this intent was detected
Next action to take (e.g., 'setup_pipeline', 'execute_retriever')
Whether to ask user for clarification
Existing collections that might help
Show child attributes
Show child attributes
Options for user if clarification needed
Show child attributes
Show child attributes
Keywords found (setup_keywords, execution_keywords, neutral_keywords)
Show child attributes
Show child attributes
Was this page helpful?

