Authorizations
Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer sk_live_abc123def456"
"Bearer sk_test_xyz789"
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'
"ns_abc123def456"
"production"
"my-namespace"
Body
Records a user interaction with a search result.
This model captures user behavior signals that can be used to improve retrieval quality. Each interaction represents a user action (click, view, feedback) on a specific document returned by a retriever.
Use Cases: - Track which search results users actually click on - Collect explicit feedback (thumbs up/down) on result quality - Monitor engagement metrics (time spent viewing, sharing) - Identify problematic queries (zero results, immediate refinements) - Power Learning to Rank models with real user behavior
Requirements: - feature_id: REQUIRED - The document/feature that was interacted with - interaction_type: REQUIRED - Type(s) of interaction that occurred - position: OPTIONAL - Where in results list the interaction occurred - metadata: OPTIONAL - Additional context about the interaction - user_id: OPTIONAL - For personalization and user-specific metrics - session_id: OPTIONAL - For tracking multi-query sessions
Related Concepts: - Retrievers: Interactions measure retriever performance - Evaluations: Interactions provide real-world complement to offline evaluation - Learning to Rank: Interactions train ranking models
ID of the document/feature that was interacted with. REQUIRED. This should be the document_id returned in retriever results. Used to track which specific items users engage with.
"doc_abc123"
"prod_xyz789"
"feat_12345"
List of interaction types that occurred. REQUIRED. Multiple types can be recorded simultaneously (e.g., VIEW + CLICK + LONG_VIEW for a result the user engaged with). Use the InteractionType enum values.
1["click"]["positive_feedback", "click", "long_view"]["negative_feedback"]["purchase", "click"]Position in search results where interaction occurred (0-indexed). NOT REQUIRED. Critical for Learning to Rank - helps identify position bias. E.g., position=0 means first result, position=9 means 10th result. Higher engagement at lower positions suggests higher quality.
x >= 00
1
5
15
Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.
{
"device": "mobile",
"duration_ms": 5000,
"page": "search_results",
"viewport_position": 0.75
}{
"interaction_reason": "not_relevant",
"page_number": 2,
"results_count": 50,
"search_latency_ms": 150
}Customer's authenticated user identifier. NOT REQUIRED. Persists across sessions for long-term tracking. Enables personalization and user-specific metrics. Use your application's user ID format.
"user_abc123"
"customer_456"
"usr_xyz789"
Temporary identifier for a single search session. NOT REQUIRED. Typically 30min-1hr duration. Tracks anonymous and authenticated users within a session. Use to group related queries and understand search journeys.
"sess_abc123"
"session_xyz789_1234567890"
Response
Successful Response
Response model for a stored interaction.
Extends SearchInteraction with system-assigned fields.
ID of the document/feature that was interacted with. REQUIRED. This should be the document_id returned in retriever results. Used to track which specific items users engage with.
"doc_abc123"
"prod_xyz789"
"feat_12345"
List of interaction types that occurred. REQUIRED. Multiple types can be recorded simultaneously (e.g., VIEW + CLICK + LONG_VIEW for a result the user engaged with). Use the InteractionType enum values.
1["click"]["positive_feedback", "click", "long_view"]["negative_feedback"]["purchase", "click"]Unique identifier for this interaction record. System-assigned UUID. Use this to reference the interaction in subsequent requests.
"int_abc123xyz789"
"550e8400-e29b-41d4-a716-446655440000"
Position in search results where interaction occurred (0-indexed). NOT REQUIRED. Critical for Learning to Rank - helps identify position bias. E.g., position=0 means first result, position=9 means 10th result. Higher engagement at lower positions suggests higher quality.
x >= 00
1
5
15
Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.
{
"device": "mobile",
"duration_ms": 5000,
"page": "search_results",
"viewport_position": 0.75
}{
"interaction_reason": "not_relevant",
"page_number": 2,
"results_count": 50,
"search_latency_ms": 150
}Customer's authenticated user identifier. NOT REQUIRED. Persists across sessions for long-term tracking. Enables personalization and user-specific metrics. Use your application's user ID format.
"user_abc123"
"customer_456"
"usr_xyz789"
Temporary identifier for a single search session. NOT REQUIRED. Typically 30min-1hr duration. Tracks anonymous and authenticated users within a session. Use to group related queries and understand search journeys.
"sess_abc123"
"session_xyz789_1234567890"