Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Public Retriever API

Track Interaction

Track user interaction with search results.

Records user engagement (clicks, views, etc.) for analytics and potential search optimization (Learning to Rank).

Authentication:

  • API key is OPTIONAL (same as execute endpoint)
  • Password NOT required (tracking should work even without auth)

Recommended Headers:

  • X-Session-ID: Session identifier for tracking user journey

Interaction Types:

  • VIEW: Result was visible in viewport
  • CLICK: User clicked on result
  • POSITIVE_FEEDBACK: User explicitly liked result
  • NEGATIVE_FEEDBACK: User explicitly disliked result
  • PURCHASE: User purchased/converted
  • ADD_TO_CART: User added to cart
  • WISHLIST: User added to wishlist
  • LONG_VIEW: User spent significant time viewing
  • SHARE: User shared result
  • BOOKMARK: User bookmarked result

Example:

curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/interactions" \
  -H "X-Session-ID: sess_xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_123",
    "interaction_type": ["CLICK"],
    "position": 2,
    "execution_id": "exec_abc",
    "query_snapshot": {"query": "red car"}
  }'
post/v1/public/retrievers/{public_name}/interactions

Path parameters

public_namestring required

Public name of the published retriever

Public name of the published retriever

Headers

X-Session-IDstring nullable
X-Public-API-Keystring nullable

Request body

document_idstring required

ID of the document that was interacted with (from search results)

interaction_typeInteractionType[] required

Type(s) of interaction that occurred

positioninteger required

Position in search results (0-indexed)

execution_idstring nullable

ID of the retriever execution that generated these results. HIGHLY RECOMMENDED for analytics.

query_snapshotobject nullable

Snapshot of the query that generated these results. HIGHLY RECOMMENDED for training optimization.

document_scorenumber nullable

Initial retrieval score of this document

result_set_sizeinteger nullable

Total number of results shown

session_idstring nullable

Session identifier for tracking user journey

metadataobject nullable

Additional context about the interaction

Example request

{
  "document_id": "doc_abc123",
  "interaction_type": [
    "click"
  ],
  "execution_id": "exec_abc123xyz",
  "query_snapshot": {
    "text": "wireless headphones"
  },
  "document_score": 0.95,
  "result_set_size": 10,
  "session_id": "sess_abc123"
}

Response

Successful Response

{"stackTrail":"paths:/v1/public/retrievers/{public_name}/interactions:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}