> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autocomplete: Get Suggestions

> Autocomplete API endpoint returning ranked search-query suggestions as shoppers type into your storefront search bar.

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](/api-reference/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

<ParamField header="X-Storefront-Access-Token" type="string" required>
  Token-based authentication header in the form of `<YOUR_LAYERS_TOKEN>`.
</ParamField>

## Headers

<ParamField header="Content-Type" type="string" default="application/json" required />

<ParamField header="Accept" type="string" default="application/json" required />

## Query parameters

<ParamField query="query" type="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.
</ParamField>

## Response

<ResponseField name="matchedQueries" type="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.
</ResponseField>

<ResponseField name="originalQuery" type="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.
</ResponseField>

<ResponseField name="normalizedQuery" type="string | null">
  The lowercased, trimmed form of `originalQuery` used internally for matching. `null` when no query was effectively provided.
</ResponseField>

<ResponseField name="_meta" type="object">
  Optional metadata. Present only when a [semantic redirect](/platform/semantic-redirects) matches the current query.

  <Expandable title="Properties">
    <ResponseField name="redirect" type="object">
      <Expandable title="Properties">
        <ResponseField name="url" type="string">
          The destination URL the storefront should navigate to. Suggestions are still returned alongside the redirect — your frontend decides whether to follow the redirect immediately or render the suggestion list.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **Semantic Redirects**: When the autocomplete query semantically matches a configured [semantic redirect](/platform/semantic-redirects) 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.
</Note>

## 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](/platform/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.

<ResponseExample>
  ```json Response theme={null}
  {
      "matchedQueries": [
          "sup",
          "supreme"
      ],
      "originalQuery": "sup",
      "normalizedQuery": "sup"
  }
  ```

  ```json Response (with semantic redirect) theme={null}
  {
      "matchedQueries": [
          "support"
      ],
      "originalQuery": "support",
      "normalizedQuery": "support",
      "_meta": {
          "redirect": {
              "url": "https://yourstore.com/pages/contact-us"
          }
      }
  }
  ```

  ```json Response (no query — trending suggestions) theme={null}
  {
      "matchedQueries": [
          "summer dresses",
          "linen shirts",
          "white sneakers"
      ],
      "originalQuery": null,
      "normalizedQuery": null
  }
  ```
</ResponseExample>