Skip to main content
Returns a list of relevant Items for a user search query. Personalization can be achieved by providing a user_id or session_id. This also allows for model relevance improvements through event feedback.

​
Endpoint

POST /v1/search

​
Request Body

FieldTypeRequiredDescription
queryStringYesThe user’s search query text. Example: ‘workshop desk’
user_idStringNoUnique identifier for the user performing the search.
session_idStringNoUnique identifier for the user’s current session.
eventsArrayNoA list of events associated with the request. Example: [{"timestamp":"2024-06-14T10:00:00Z","type":"search","description":"User searched for workshop desk"}]
limitIntegerNoMaximum number of search results to return. Defaults to 50.

​
Example Request

Example Body
{
  "query": "workshop desk",
  "limit": 10
}

​
Response Body

Returns a JSON object containing the search results.
FieldTypeDescription
itemsArrayAn array of item IDs. Example: ["ST678VG","QW1234","EC5792"]

​
Hit Object (within items array if scores are requested, otherwise just item IDs)

Each object in the items array is an ItemScore object. The provided example shows a simple list of ItemScores.
FieldTypeDescription
item_idStringThe unique identifier of the result item.
scoreFloatThe search relevance/ranking score assigned by the model (if scores are returned).
metadataObjectOptional: Additional item metadata (e.g., title, description, price, imageUrl).
Example Response
{
  "items": [
    {"id": "ST678VG", "score": 0.95},
    {"id": "QW1234", "score": 0.87},
    {"id": "EC5792", "score": 0.78}
  ]
}

​
Responses

  • 200 OK: Successful Response (ItemResponse)
  • 422 Validation Error: (HTTPValidationError)
  • 401 Unauthorized: Invalid or missing API key.
  • 429 Too Many Requests: Rate limit exceeded.
  • 5xx Server Error: An internal error occurred.