Autocomplete API

Returns discovery content, search suggestions, categories, and product cards for the authenticated store.

Endpoint

GET /api/v1/autocomplete

Query parameters

Parameter	Type	Required	Default	Description
q	string	No	Empty string	Search query. Blank queries return discovery results for an empty input.
limit	integer	No	5	Maximum number of suggestions and products to return per group.

q may be blank and may contain up to 100 characters. limit must be between 1 and 20.

Request

curl 'https://app.example.com/api/v1/autocomplete?q=run&limit=5' \
  -H 'X-Api-Key: if_PLACEHOLDER_KEY'

Response

{
  "suggestions": [
    "running shoes",
    "road running shoes"
  ],
  "categories": [
    {
      "title": "Running Shoes",
      "url": null
    }
  ],
  "products": [
    {
      "id": "STORE_PUBLIC_PRODUCT_UUID",
      "title": "Road Running Shoe",
      "category": "Running Shoes",
      "url": "https://shop.example.com/products/road-running-shoe",
      "image_url": "https://cdn.example.com/products/1001.jpg",
      "price": "99.99",
      "currency": "USD",
      "in_stock": true
    }
  ],
  "meta": {
    "query": "run",
    "mode": "search",
    "store": "STORE_UUID",
    "cached": false,
    "source": "graph",
    "counts": {
      "suggestions": 2,
      "categories": 1,
      "products": 1
    }
  }
}

Response modes

Mode	When	Returned groups
discovery	q is blank, normally when the shopper focuses an empty search field.	Latest/trending products, recent search expressions, and store categories.
search	q contains a search term.	Matching products, matching categories, and autocomplete suggestions.

Product object

Field	Type	Description
id	string	Public product UUID. Numeric IDs are not exposed.
title	string	Product title.
category	string or null	Merchant-supplied product category.
url	string	Public product URL.
image_url	string or null	Product image URL.
price	string	Decimal price formatted as a string.
currency	string	Store currency.
in_stock	boolean	Whether the product is currently available.

Category object

Field	Type	Description
title	string	Category label.
url	string or null	Optional category landing page. Currently null when categories come from the product import feed.

Ranking

Results are ranked with these current rules:

1. In-stock products first.
2. Exact title match.
3. Title prefix match.
4. Generated intent phrase match.
5. Popularity (recent clicks and purchases from tracked search events, time-decayed).
6. Alphabetical fallback.

Suggestions are ranked by measured value: clicked suggestions rank above unclicked ones for the same prefix.

PLACEHOLDER: Add final rules for conversion, margin, merchandising boosts, and synonyms.

Caching and serving source

Autocomplete responses are cached for 60 seconds by store, query, and limit. The response includes meta.cached.

meta.source reports how an uncached response was computed:

Source	Meaning
graph	Served from the store's precomputed intent prefix graph — ready-made ranked answers for short prefixes.
backend	Computed by the configured search backend (database, Meilisearch, or Typesense).

Both sources return the same response shape; the field exists for observability and requires no client handling.

Example empty response

{
  "suggestions": [
    "best running shoes"
  ],
  "categories": [
    {
      "title": "Running Shoes",
      "url": null
    }
  ],
  "products": [
    {
      "id": "STORE_PUBLIC_PRODUCT_UUID",
      "title": "Road Running Shoe",
      "category": "Running Shoes",
      "url": "https://shop.example.com/products/road-running-shoe",
      "image_url": "https://cdn.example.com/products/1001.jpg",
      "price": "99.99",
      "currency": "USD",
      "in_stock": true
    }
  ],
  "meta": {
    "query": "",
    "mode": "discovery",
    "store": "STORE_UUID",
    "cached": false,
    "source": "backend",
    "counts": {
      "suggestions": 1,
      "categories": 1,
      "products": 1
    }
  }
}