Search API - Sequen AI Docs

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

Field	Type	Required	Description
`query`	String	Yes	The user’s search query text. Example: ‘workshop desk’
`user_id`	String	No	Unique identifier for the user performing the search.
`session_id`	String	No	Unique identifier for the user’s current session.
`events`	Array	No	A list of events associated with the request. Example: `[{"timestamp":"2024-06-14T10:00:00Z","type":"search","description":"User searched for workshop desk"}]`
`limit`	Integer	No	Maximum 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.

Field	Type	Description
`items`	Array	An 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.

Field	Type	Description
`item_id`	String	The unique identifier of the result item.
`score`	Float	The search relevance/ranking score assigned by the model (if scores are returned).
`metadata`	Object	Optional: 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.