Skip to main content
GET
/
search
/
complete?query=
{query}
Autocomplete: Get Suggestions
curl --request GET \
  --url 'https://app.uselayers.com/api/storefront/v1/search/complete?query={query}' \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>'
{
    "matchedQueries": [
        "sup",
        "supreme"
    ],
    "originalQuery": "sup",
    "normalizedQuery": "sup"
}
The Autocomplete endpoint returns ranked query-text suggestions for a partial search term. It does not return products, product previews, or images — use the Search endpoint to fetch products for a chosen suggestion. When no query is provided, the endpoint returns the store’s top trending queries (subject to the same brand curation rules as live suggestions).

​
Authorization

​
X-Storefront-Access-Token
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

​
Headers

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

​
Query parameters

​
query
string
The partial query you want suggestions for. Maximum 255 characters. Sanitized server-side; queries shorter than 2 characters after sanitization are treated as empty and return trending suggestions instead.

​
Response

​
matchedQueries
string[]
Ranked array of suggestion strings. Prefix matches appear first, followed by non-prefix matches that clear the relevance threshold. Each string is the suggestion text the shopper should see — either the cluster’s canonical query or its curated display label when one is configured.
​
originalQuery
string | null
The query value exactly as sent by the client. null when the request omits query or when the sanitized query is too short.
​
normalizedQuery
string | null
The lowercased, trimmed form of originalQuery used internally for matching. null when no query was effectively provided.
​
_meta
object
Optional metadata. Present only when a semantic redirect matches the current query.
Semantic Redirects: When the autocomplete query semantically matches a configured semantic redirect term, the response includes a _meta.redirect object with the redirect URL. This lets you redirect users directly from the typeahead experience before they submit a full search.

​
Suggestion quality

Layers applies several techniques to keep autocomplete suggestions relevant and concise.

​
Brand curation

You can layer a natural-language brand prompt on top of the default suggestion pipeline. Layers uses the prompt — together with your store description — to suppress off-brand suggestions and rewrite display labels for customers. Suppressed clusters never appear in matchedQueries, and curated clusters return their rewritten text in place of the canonical query. Matching against raw customer queries is unchanged. See Autocomplete curation for configuration details.

​
Stem deduplication

Autocomplete automatically collapses singular and plural variants of the same word into a single suggestion. For example, if your query data contains both “diamond” and “diamonds”, only the higher-scoring canonical form is returned. This also applies to other English stem variations like “berry” and “berries” or “long sleeve” and “long-sleeve”. Stem awareness extends to query matching as well. When you search for “diamonds”, autocomplete finds suggestions containing the singular “diamond” and vice versa. This means singular and plural queries produce identical suggestion lists, so your customers see the same results regardless of which form they type. When multiple suggestions share the same stem, the suggestion with the highest relevance score is kept. Shorter canonical forms (typically the singular) win ties, which keeps the suggestion list clean and predictable.

​
Relevance gating

Suggestions that don’t closely match the query text are filtered out before results are returned. Prefix matches (where the query is the beginning of a suggestion) always pass through. Non-prefix matches must meet a minimum text-similarity threshold to appear. This prevents semantically distant suggestions from surfacing alongside direct matches. 
{
    "matchedQueries": [
        "sup",
        "supreme"
    ],
    "originalQuery": "sup",
    "normalizedQuery": "sup"
}