Skip to content
Elara One docs
Search

Get search suggestions

GET
/v1/search/suggest

Grouped suggestions for the typed query: products, collections, brands, tags, CMS pages and posts (only the groups asked for in types that the store has enabled, each with its merchant limit). *_html fields are escaped text plus <mark>/</mark> only. Below the store's min_chars the answer is 200 with empty groups; with search switched off it is 200 with no groups and meta.search_engine: "disabled". When Meilisearch is unavailable the answer is still 200: products from the database, the other groups empty, meta.search_engine: "database", Cache-Control: no-store, private (never cached). A searched answer carries X-Search-Total (products total) and a fresh X-Search-Id (ULID) for the search beacons, even when served from the response cache (kept 300 s, dropped on every index write).

Authorization

tenantKey
headerX-Tenant-Key<token>

The public store key (pk_live_…). Required on every call.

Query Parameters

q*string

The typed text, 1–200 characters after trimming. Shorter than the store's min_chars: 200 with empty groups, nothing searched.

Lengthlength <= 200
locale?|

A store language code as listed in locales[].code (e.g. en, fr). Missing or unknown: the store default; meta.locale says which was used.

Lengthlength <= 35
types?|

Comma-separated subset of products,collections,brands,tags,pages. Missing: every group the store has enabled. Unknown or disabled values are ignored.

Lengthlength <= 200

Header Parameters

X-Client-IP?string

Optional. IP address of the shopper (one IPv4/IPv6, no port, no list). Honoured only together with a valid X-Tenant-Secret; ignored otherwise. Used for rate limits and recorded with form submissions.

X-Tenant-Secret?string

Optional here. Server secret of the store: server-to-server only, never from a browser. Enables X-Client-IP.

Response Body

Success.

application/json
  1. response
data*
meta*
Example Request
curl -X GET 'https://api.elaraone.app/api/v1/search/suggest?q=walnut+de&locale=en&types=products%2Ccollections%2Cbrands%2Ctags%2Cpages' \  -H 'X-Tenant-Key: pk_live_…' \  -H 'X-Tenant-Secret: your-server-secret'
Example Response
{  "data": {    "query": "string",    "products": {      "total": 0,      "hits": [        {          "id": 0,          "slug": "string",          "name": "string",          "name_html": "string",          "sku": "string",          "brand": "string",          "short_description": "string",          "image": {            "url": "string",            "url_medium": "string",            "alt": "string"          },          "price": {            "amount": 0,            "currency": "string",            "formatted": "string"          },          "price_max": {            "amount": 0,            "currency": "string",            "formatted": "string"          },          "sale_price": {            "amount": 0,            "currency": "string",            "formatted": "string"          },          "sale_price_max": {            "amount": 0,            "currency": "string",            "formatted": "string"          },          "on_sale": true,          "in_stock": true,          "default_variant_id": 0        }      ]    },    "collections": {      "total": 0,      "hits": [        {          "id": 0,          "slug": "string",          "name": "string",          "name_html": "string",          "path": [            "string"          ],          "product_count": 0,          "image": {            "url": "string",            "url_medium": "string",            "alt": "string"          }        }      ]    },    "brands": {      "total": 0,      "hits": [        {          "id": 0,          "slug": "string",          "name": "string",          "name_html": "string",          "product_count": 0        }      ]    },    "tags": {      "total": 0,      "hits": [        {          "value": "string",          "name": "string",          "name_html": "string",          "product_count": 0        }      ]    },    "pages": {      "total": 0,      "hits": [        {          "slug": "string",          "kind": "page",          "title": "string",          "title_html": "string",          "excerpt": "string"        }      ]    },    "posts": {      "total": 0,      "hits": [        {          "slug": "string",          "kind": "post",          "title": "string",          "title_html": "string",          "excerpt": "string"        }      ]    }  },  "meta": {    "search_engine": "meilisearch",    "locale": "string",    "currency": "string"  }}

Search products GET

Full product cards for a results page. For the same `q` and `locale` with no filters, `meta.total` equals the suggest endpoint's `data.products.total`. An empty `q` with a filter is a browse (e.g. every product with a tag). `meta.facets` counts the store's facets (Meilisearch only; empty on the database fallback), `meta.facet_labels` names them and `meta.facet_value_labels` names identifier values (`brand_slug` => brand names). Prices in filters are integer minor units of `meta.currency`. Every 200 carries `X-Search-Total` (equal to `meta.total`) and a fresh `X-Search-Id` header (a ULID) for click beacons, cached body or not.

Get search settings GET

The store's public instant-search settings for one locale: autocomplete limits and timing, appearance, overlay, voice and analytics switches, and the localised placeholder and no-results text. `meta.version` changes on every settings save (clear any suggestion cache then). Cache it for 60 s; revalidate with `If-None-Match` for a bodyless `304`.