Search API

Purpose

The Search API powers shopper-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.

Capabilities

• Built-in filtering and sorting in the same /v1/search/component call
• Typo-tolerant fuzzy matching
• Synonym handling and redirect logic to recover poor or uncommon queries (see Synonyms)

Search behavior is configured in the Portal, so it can be changed without frontend code changes or redeploys. Queries can be tested in the Search Playground.

Authentication

Every request must include the API key in the request header.

Base URL: https://api-yoursite.malachyte.com (the client's Malachyte contact provides the exact URL for each store).

Endpoint

POST /v1/search/component

Retrieval Modes (Choose Exactly One)

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

Use this to get 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/component

{
"query": "White Dress",
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"k": 500,
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Option 2: Pagination Mode

Used for paged results or infinite scroll.

First Request (Choose One)

Option A — Query-driven

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

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

{
"query": "White Dress",
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Option B — Payload-driven

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

Example Request: POST /v1/search/component

{
"query": "White Dress",
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"k": 20,
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Subsequent Requests

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

Example Request:

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

{
"query": "White Dress",
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Pagination Details

Pagination Parameters

Use these query parameters in Pagination Mode (Option A):

For example, with size=40, page=1 returns results 1–40 and page=2 returns results 41–80 (for example, when the shopper clicks "Page 2" or "Load more").

Total Result Count

The search response can include a total count of matching results, which can be used for display text like "Showing 41–80 of 312 results."

{
"strategy_name": "search",
"total_results": 312,
"results": [...]
}

• Estimated before filters: The count is calculated before any filters (price, size, color, etc.) are applied, so a filtered search may show a higher total than the number of results that can actually be paged through.
• Capped at 10,000: Very broad searches will report a maximum of 10,000 results.

Pagination Depth

Search ranks a fixed number of top results. Within that depth, results stay in a consistent order across pages.

Implementation Checklist

Request Body Fields

Filtering and Sorting

Filtering and sorting are handled within the POST /v1/search/component call described above.

• Filtering: pass search_filters in the request body. Search uses the same Filter object as PLP. See Filtering in the Listing Request for the full structure and supported operators.
• Sorting: pass sort_order in the request body. If it's left out, results use RECOMMENDED.

Supported Sort Orders

Example Request (filtered by color, sorted by price, low to high): POST /v1/search/component

{
"query": "White Dress",
"search_component_id": "7b6c5432-e89b-12d3-a456-426614174000",
"visitor_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"k": 20,
"sort_order": "LOW_HIGH",
"search_filters": [
{
"key": "color",
"values": ["White"],
"comparison": "EQUAL"
}
],
"return_filters": true
}

Example Response

A trimmed response (2 of 83 results):

{
  "strategy_name": "search",
  "results": [
    { "score": 0.97, "facts": { "product_id": 123456 } },
    { "score": 0.96, "facts": { "product_id": 234567 } }
  ],
  "total_results": 83,
  "assigned_filter_values": {},
  "search_filters": []
}

• results: the matching products, in ranked order. Each has a score and its product data in facts.
• facts: the product fields set up for the search component. Some setups return only product_id, and the storefront looks up the rest of the product details itself.
• total_results: the estimated number of matches. See Total Result Count.
• assigned_filter_values / search_filters: filled in only when return_filters is true.

Error Responses

Errors return the matching HTTP status code and a JSON body with a detail message:

{
"detail": "Search component request must include a search_component_id"
}

Attribution & Identity

• visitor_id: A UUID that identifies the shopper's current session. Keep it the same for the whole session.
• user_id: Identifies a logged-in shopper and stays the same across sessions.

Testing in the Playground

Paginated results can be previewed in the Search Playground in the Portal. See Search Playground for how it works.