Search API — Design Overview

Purpose

The Search API powers user-facing search while supporting:

Accurate attribution across search, clicks, and conversions.
Flexible retrieval via either large-k retrieval or pagination.
Frontend-driven execution with backend-managed intelligence.

Endpoint

POST /v1/search

Retrieval Modes (Choose Exactly One)

[!IMPORTANT] Clients must select exactly one retrieval model per search session. Mixing parameters between these modes will result in an error.

Option 1: Large-k Mode (Single Full Result Set)

Used when the client wants the entire result set in a single response.

Rules:

k must be provided in the request body.
Pagination parameters (page, size) are not allowed.
No follow-up page requests.

Example Request: POST /v1/search

{
  "query": "White Dress",
  "strategy_name": "search",
  "k": 500,
  "from_portal": false,
  "log_response": true,
  "visitor_id": "3e92322a-d473-4c81-ab80-82dba7c31e65"
}

Option 2: Pagination Mode

Used for paged results or infinite scroll.

First Request (Choose One)

Option A — Payload-driven

Include k in the request body.
Do not include query parameters in the URL.

Example Request: POST /v1/search

{
  "query": "White Dress",
  "strategy_name": "search",
  "k": 20,
  "from_portal": false,
  "log_response": true,
  "visitor_id": "3e92322a-d473-4c81-ab80-82dba7c31e65"
}

Option B — Query-driven

Include page and size in the query string.
Do not include k in the request body.

Example Request: POST /v1/search?page=1&size=20

{
  "query": "White Dress",
  "strategy_name": "search",
  "from_portal": false,
  "log_response": true,
  "visitor_id": "3e92322a-d473-4c81-ab80-82dba7c31e65"
}

Subsequent Requests Must include only page and size k must not be included

POST /v1/search?page=2&size=20

{
  "query": "White Dress",
  "strategy_name": "search",
  "from_portal": false,
  "log_response": true,
  "visitor_id": "3e92322a-d473-4c81-ab80-82dba7c31e65"
}

Request Body Fields

Field	Type	Required	Description
`query`	string	Yes	Search term entered by the user.
`strategy_name`	string	Yes	Always `"search"`.
`k`	number	Conditionally	Required for Large-k mode or first request in Pagination Option A.
`from_portal`	boolean	Yes	Must always be `false` for end-user traffic.
`log_response`	boolean	Yes	Must always be `true`.
`visitor_id`	string (UUID)	Yes	Persistent identifier for attribution and analytics.

Filtering API

POST /v1/search/filter

Filters an existing set of search results based on specific user criteria.

Request Fields

results: List of search results (typically retrieved from /v1/search).
strategy: Reserved for future use.
filters: List of filters applied to exclude specific results.

Result

Returns a filtered list of recommendations based on the provided logic.

Sorting API

POST /v1/search/sort

Sorts an existing set of search results based on the selected ordering.

Supported Sort Orders

Value	Description
`RECOMMENDED`	Existing relevance score
`A_Z`	Alphabetical (A → Z)
`Z_A`	Alphabetical (Z → A)
`HIGH_LOW`	Price: High → Low
`LOW_HIGH`	Price: Low → High
`NEW_OLD`	Newest → Oldest
`OLD_NEW`	Oldest → Newest

Result

Returns a sorted list of recommendations.

Attribution & Identity

[!TIP] Data Integrity & Tracking These fields are essential for measuring search performance and ROI.

log_response = true: Enables full attribution tracking across search, click, and conversion events.
visitor_id: A persistent identifier (UUID) that ensures consistent identity and accurate analytics across multiple user sessions.

API

On this page