Indexa API

API reference

Indexa is a managed search & discovery engine for Shopify storefronts. This reference covers the two surfaces your integration talks to: the search engine (typo-tolerant keyword + semantic search) and the indexer service (recommendations, events, reindex and webhooks). Hosts and keys are provisioned for you at onboarding — this document is how you query them.

Your Shopify catalog is synced into a dedicated search index, one collection per language (products_it, products_en). Three components are involved:

Three credential types, each with a different scope. Never expose the admin key client-side.

Search key

A read-only key scoped to documents:search on your language collections only. Safe to ship in the storefront. Sent as a header on every search call:

X-TYPESENSE-API-KEY: {your_search_key}

Admin key

A bearer token for the indexer's /admin/* routes (reindex, mint a search key). Server-side only.

Authorization: Bearer {your_admin_key}

Webhook signature

Shopify signs product webhooks with your shared secret; the indexer verifies the X-Shopify-Hmac-Sha256 header and rejects anything unsigned in production.

Every tenant gets its own isolated hosts — there is no shared public gateway. Your exact URLs are delivered at onboarding and shown in your console under API keys. The examples below use the two environment variables you set in your storefront.

Languages default to it, en. Every collection name is products_{lang}.

Search the Italian collection for a plain-language query:

curl -X POST "$TYPESENSE_URL/multi_search" \
  -H "X-TYPESENSE-API-KEY: $SEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [{
      "collection": "products_it",
      "q": "maglione verde",
      "query_by": "title,vendor,model_code,sku,tags,primary_category",
      "query_by_weights": "6,3,4,4,2,2",
      "sort_by": "_text_match:desc,score:desc",
      "per_page": 12
    }]
  }'

All searches go through a single endpoint. The body is always { "searches": [ SearchParams ] }; you may batch several searches in one call.

Parameters

Query understanding

Before searching, Indexa parses attributes out of the raw term and turns them into filters — so "maglione verde taglia XL" filters by colour and size instead of matching those words as text. Sizes and colours are read from your live facet vocabulary; gender is resolved separately.

• • Sizes — matched to the sizes facet (e.g. xl → XL).
• • Colours — matched to the colors facet, including Italian gender/number inflections (nero → nera/nere/neri, verde → verdi).
• • EN → IT synonyms — green→Verde, black→Nero, blue→Blu, red→Rosso… added only when the Italian value exists in the facet.
• • Stopwords dropped: da, di, del, con, per, the, of, for, with, and…

Detected attributes become filter clauses, joined with the caller's gender filter:

gender:=Donna && colors:=["Verde"] && sizes:=["XL"]

Filtering & facets

filter_by uses Typesense syntax: field:=value (exact), field:=[a,b] (any of), price:>=n / price:<=n (range), joined with &&. Storefront URL parameters map to filters like this:

Sorting & pagination

The default sort is relevance then score: _text_match:desc,score:desc. score is a blended rank (popularity, discount, freshness, availability) computed at index time. Sortable fields: price, discount_pct, popularity, published_at, score. Page size is up to 250.

Semantic (hybrid) search

When embeddings are enabled, append the embedding field to query_by with a trailing weight and set prefix: false. Keyword relevance and vector similarity are fused in one call — no separate vector query needed.

{
  "searches": [{
    "collection": "products_it",
    "q": "qualcosa di caldo per l'inverno",
    "query_by": "title,vendor,model_code,sku,tags,primary_category,embedding",
    "query_by_weights": "6,3,4,4,2,2,1",
    "prefix": false,
    "exclude_fields": "embedding",
    "sort_by": "_text_match:desc,score:desc",
    "per_page": 24
  }]
}

The response

Results come back under results[0].hits; each hit's document is a product (see Product schema). facet_counts is present when you pass facet_by.

{
  "results": [{
    "found": 128,
    "hits": [{
      "document": {
        "id": "7523891",
        "title": "Maglione girocollo in lana",
        "vendor": "Atelier Nord",
        "price": 39.90,
        "compare_at_price": 59.90,
        "discount_pct": 33,
        "colors": ["Verde"],
        "sizes": ["S","M","L","XL"],
        "image_url": "https://cdn.shopify.com/.../maglione.jpg",
        "url": "/it/products/maglione-girocollo-lana"
      },
      "text_match": 1157451471441100900
    }],
    "facet_counts": []
  }]
}

Merchandising rules pin, hide and boost products in both search results and category pages. Rules are authored and managed in your console — there is no public write endpoint for them — and are read at query time by the same shared query builder that assembles every other Indexa search.

The rule model

Rules live in a merch_rules table on the control plane. Each row has:

Rule selection

At most one rule applies to a given search. Selection is deterministic — it never depends on the order rules happen to be stored or fetched in:

• • Exact beats contains — a scope: query rule with match_type: exact matching the whole normalized query wins over any contains rule.
• • Longest target wins among contains rules — if the query contains more than one rule's target as a substring (e.g. "scarpe" and "scarpe donna"), the longer, more specific target is selected.
• • Ties broken by the lowest rule id — when two competing contains targets have equal length, the rule with the lower id wins.
• • Collection rules match the handle exactly — match_type is not considered for scope: collection.

Matching is case-insensitive and ignores leading/trailing whitespace on both the rule target and the incoming query or handle.

From rules to request parameters

The selected rule is not pushed into Typesense as a stored override object. It is translated, at query time, into two parameters on the same /multi_search call used for every other search:

// merch_rules row
"pinned_ids": ["4102938", "4109221"]

// Typesense request parameter
"pinned_hits": "4102938:1,4109221:2"

Category pages

A category listing is not a separate endpoint — it is the same /multi_search request, assembled by the same shared query builder, with:

• • q set to * (match everything).
• • A collection filter added to filter_by, with the handle backtick-quoted: collections:=[`handle`].
• • The merchandising rule lookup run with scope: 'collection' instead of scope: 'query'.

collections:=[`giacche-uomo`]

For a wildcard query, _text_match is dropped from sort_by — it is meaningless when there is no query text to match against:

score:desc

_eval(collections:=[`giacche-uomo`]):desc,score:desc

Pinned-product edge cases

Verified against a live Typesense 27.1 instance — two behaviors worth knowing before you rely on pinning:

• • Pinning an id outside the result set leaves no gap. If a pinned product would not otherwise appear in the results, the remaining hits simply fill in — there is no empty slot left where it would have been.
• • A pinned product that fails filter_by is excluded, not injected. filter_curated_hits (above) means pinning never overrides an active filter — a pinned product a shopper's facets rule out just does not show up.

The storefront proxy exposes an instant-search endpoint that runs a keyword search plus popular-query suggestions and returns render-ready product cards.

{
  "products": [ { "id": "gid://shopify/Product/7523891", "title": "Maglione…", "handle": "…", "price": {…} } ],
  "queries":  [ { "text": "maglione donna", "styledText": "maglione <b>donna</b>" } ]
}

Six recommendation types on the indexer service. Shopify-backed types return full products[]; analytics-backed types return ordered product_ids[] you resolve against your catalog.

curl "$INDEXER_URL/reco/best-sellers?lang=it&limit=8&collection=donna"

{
  "products": [
    { "id": "7523891", "handle": "felpa-cappuccio-donna", "title": "Felpa con cappuccio",
      "price": 29.99, "image_url": "https://cdn.shopify.com/.../felpa.jpg",
      "url": "/it/products/felpa-cappuccio-donna" }
  ]
}

Send interaction beacons so Indexa can power popularity, "also viewed" and analytics. No auth — it's a public, fire-and-forget beacon.

curl -X POST "https://store.example/it/api/ts-event" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "7523891", "event_type": "click", "sid": "a1b2c3" }'

Returns { "ok": true }. An unknown event_type returns 400.

Every indexed product — and every search hit — has this shape.

Shopify product changes are pushed to the indexer, which upserts or deletes the document in every language collection in real time. You point Shopify at one of three routes.

• • Signature header X-Shopify-Hmac-Sha256, verified against your webhook secret.
• • Responds 200 {"received":true} immediately, then processes asynchronously (no Shopify timeout).
• • Missing / invalid signature → 401 {"error":"invalid hmac"}. Unsigned requests are rejected in production (fail-closed).

Server-side only. Both require the admin bearer key.

Triggers a full async reindex of all languages. Returns 202 { "started": true }.

Mints a fresh scoped search-only key. Returns 200 { "search_key": "…" }.

curl -X POST "$INDEXER_URL/admin/reindex" \
  -H "Authorization: Bearer $ADMIN_KEY"

Error bodies are JSON, e.g. { "error": "unauthorized" }.

• • Search keys are read-only and collection-scoped — safe to ship in the browser.
• • Merchandising (synonyms, pins, boosts, redirects) is managed in your console and applied to the engine for you — there is no public write endpoint for it.
• • CORS on the search engine is enabled so the storefront can query it directly.
• • Relevance weights per field and language are tuned from your real search data — the defaults above are a starting point.
• • Need higher throughput, more languages, or a dedicated region? Talk to us.