Skip to main content
POST
https://app.uselayers.com/api/storefront/v1
/
search
/
{searchQuery}
/
prepare
Text Search: Prepare Search
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>"
  ]
}
'
{
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
This endpoint asynchronously prepares expensive personalization for a given query, returning a ULID search_id that can be used with the Search API to execute the search.
  • 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. Available attributes include: id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, and first_or_matched_variant. See the Product Schemafor detailed descriptions.

​
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 15 minutes; after TTL, Search falls back to normal processing

​
Response

​
202 Accepted

​
search_id
string
ULID identifier for the prepared search. Valid for 15 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.