POST
/
search
/
{searchQuery}
/
prepare
Prepare Search: Async Search Optimization
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '{
  "attributes": [
    "<string>"
  ],
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "path": "<string>",
    "referrer_path": "<string>",
    "marketing_source": "<string>",
    "marketing_medium": "<string>",
    "marketing_campaign": "<string>",
    "marketing_term": "<string>",
    "marketing_content": "<string>",
    "cart_empty": true,
    "cart_value": 123,
    "num_cart_items": 123,
    "signed_in": true,
    "num_orders": 123,
    "geo_city": "<string>",
    "geo_state": "<string>",
    "geo_country": "<string>"
  }
}'
{
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
This endpoint prepares expensive parts of a search (embeddings and AI-powered query expansions) asynchronously for a given query, returning a ULID search_id that can be used with the Search API to execute with lower latency.
  • Use with: Search API via the search_id body parameter

​
Authorization

​
X-Storefront-Access-Token
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>. Same requirements as the Search API.

​
Headers

​
Content-Type
string
default:"application/json"
required
​
Accept
string
default:"application/json"
required

​
Path Parameters

​
searchQuery
string
required
The url-encoded search query to prepare.

​
Body

​
attributes
string[]
Optional hint for which product attributes you intend to include in the eventual Search response. If omitted, defaults will be used by the Search API.
​
tuning
object
Parameters to fine-tune the search results.
​
filter_group
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
​
pagination
Pagination Object
​
facets
string[]
Facets to be included.
​
retrieveFacetCount
boolean
If the count of each facet value should be calculated
​
includeFacetRanges
boolean
If you want a min/max range for numeric facets such as price.
​
identity
object
Information used to current identify the customer/session.
​
context
object
Anonymous contextual information of the session/customer.

​
Behavior

  • Returns HTTP 202 (Accepted) immediately with a search_id
  • Generates a ULID search_id that identifies the prepared search
  • Dispatches an asynchronous background job on a high-priority queue
  • Pre-computes embeddings and AI-powered query expansions
  • Prepared data is cached for up to 5 minutes; after TTL, Search falls back to normal processing

​
Response

​
202 Accepted

​
search_id
string
ULID identifier for the prepared search. Valid for 5 minutes.
{
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}

​
Error Conditions

  • 401 Unauthorized: Missing/invalid X-Storefront-Access-Token
  • 422 Unprocessable Entity: Invalid body or parameters

​
Next Steps

Use the returned search_id with the Search API in the search_id body parameter to execute an optimized search.