Public Retriever API

Track Interaction

Changed on

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

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions
  • Auth: none required

Path parameters

public_namestring required

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

REQUIRED. ID of the retriever execution that generated these results, as returned by the search. An interaction without it is refused (422).

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

unknown required

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 5307993e44d3Revision changes
    • info

      added the new add_to_project enum value to the request property /

    • info

      added the new download enum value to the request property /

    • info

      added the new play enum value to the request property /

    • info

      added the new rating enum value to the request property /

    • info

      added the new save enum value to the request property /