API reference

Run a search. Redirects, relevance weights, query understanding, merchandising and did-you-mean are applied server-side, in that order.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{
  "hits": [ { "id": "7523891", "title": "Maglione girocollo in lana", "price": 39.9, "…": "see Product document" } ],
  "found": 128,
  "search_event_id": "aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa",
  "facets": [ { "field_name": "vendor", "counts": [ { "value": "Atelier Nord", "count": 12 } ] } ],
  "page": 1,
  "redirect": null,
  "didYouMean": null,
  "understood": { "sizes": ["XL"], "colors": ["Verde"], "genders": ["Donna"] },
  "relaxed": { "terms": ["inverno"], "sizes": ["XL"] }
}

• • search_event_id is an optional UUID for a logged search. Carry it with query on result clicks; previews, category listings and analytics=false omit it. Logging is best effort. Analytics zero results use displayed results after relaxation; original counts remain available for debugging.
• • redirect is an answer, not a ranking: when a merchant has mapped the query to a page, hits is empty and redirect holds the target. Validate it against your own origin before navigating — the engine already refuses anything that is not a relative path or a same-origin URL.
• • Metafields declared in your console are ordinary fields here: filter_mf_<namespace>_<key> (mfv_ for variant-level ones), with the same equality, OR, and filter_not_ forms, and matching is case-insensitive. They are always indexed as string lists, so the _min/_max range form does not apply to them — it would match nothing rather than error.
• • facets carries value counts for the built-in facets, plus any metafield ticked as *Show as filter* in your console (up to 8) once it is in the index — that is what a filter sidebar is built from. Filtering a metafield never requires the tick; only knowing its values does.
• • A filter naming a field the index does not have answers 400 Unknown filter field: <name> — a bookmarked URL carrying a facet that has since been renamed is the caller's mistake, not an outage, and dropping the clause instead would answer a filtered request with the whole catalogue.
• • Filters combine as AND across parameters and OR within one field. OR *across different fields* is deliberately not expressible here: it needs a filter grammar, and a grammar on a browser-facing endpoint is a surface that cannot be closed again once it is open. If you need one, run the query server-side against /admin/preview with your admin key, which accepts a raw expression.
• • Paging is capped: page × per_page may not exceed 1000, and a request past that answers 400 rather than silently returning an earlier page. Shoppers do not reach page 11; catalogue scrapers do nothing else. Narrow with filters instead.
• • didYouMean is offered when fewer than 3 products match, and suggests a query shoppers have actually run — not a dictionary word.
• • understood reports what was pulled out of the phrase into filters — size, colour and department — so you can show it back to the shopper and let them drop one.
• • relaxed is present only when the exact query matched nothing and a weaker one was answered instead. It names what was given up, in the order the engine gives things up: trailing words first (a word the catalogue has no vocabulary for is usually a typo or a marketing phrase), then size, then colour. Never the department, and never a filter the shopper set themselves. Say it on the page — a list that silently ignores half the query reads as a broken filter.

Query suggestions for an autocomplete box, drawn from what shoppers on this store actually searched.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "queries": ["maglione donna", "maglione lana", "maglioncino"] }

Shopify's own best-selling ranking, optionally within one collection.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "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" }
] }

Shopify's product recommendations for one product.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "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" }
] }

Indexa-generated complementary products from merchant-defined categories and weighted field rules.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "product_ids": ["7523891"], "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" }
] }

• • Configure and enable rules in the Complete the look admin section. Product scope wins over custom-pick list, category and default; priority then rule ID breaks ties. One rule applies, with no merging.
• • Ranks up to 200 available candidates per destination category plus explicit pins. Weighted equality, shared values, directional compatibility, numerical distance and ratio determine ranking. Required criteria, exclusions and availability remain mandatory for pins.
• • No matching rule or eligible products returns empty products and product_ids arrays. Invalid product ID or catalog language returns 400; unavailable generation returns 503. Internal weights and explanations are never public.
• • Separate from Shopify COMPLEMENTARY: no Shopify metafield writes or automatic fallback. Playground Complete the look uses this Indexa endpoint and saved enabled rules. Use data-indexa-reco=complete-the-look in Liquid or type=complete-the-look in the Hydrogen example proxy; storefront placement is opt-in.

Most-viewed products in a rolling window, from your own traffic.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "product_ids": ["7523891", "7519001"], "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" }
] }

• • Empty until view events arrive. An empty list is the correct answer for a store with no traffic yet, not an error.

Products co-viewed in the same session as this one.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "product_ids": ["7519001"], "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" }
] }

• • Needs view events carrying a session id (sid).

A curated list, in the order a merchant arranged it in the console.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "product_ids": ["7523891", "7519001"], "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" }
] }

• • Create and edit lists in /custom-picks using catalog search, product thumbnails and drag-and-drop order. Use the saved slug in this endpoint; list creation does not install a storefront carousel. Missing or unavailable products are omitted from resolved products.

Interaction beacon. The only public endpoint that writes, and the only source of data for the popular and people-also-viewed models.

X-Indexa-Key: $PUBLIC_KEY from a browser, $SECRET_KEY from your own server — or ?key= where headers are impossible (sendBeacon).

{ "product_id": "7523891", "event_type": "view", "lang": "it", "sid": "a1b2c3d4" }

(no body)

• • Result clicks should include query (up to 512 chars) and search_event_id (UUID from /search). Optional quantity is a positive integer up to 100000. Both sid and session_id are supported.
• • Revenue, unit_price, currency, order_id, source and created_at from this public endpoint are ignored, including with sk_ keys. Browser purchase events never contribute authoritative revenue or conversion. Send only after required analytics consent.
• • Verified purchases come from POST /webhooks/orders/paid with Shopify raw-body HMAC, shop domain and orders/paid topic headers. The indexer acknowledges after duplicate-safe storage; failures return 503 for retry. Configure the tenant Shopify subscription and preserve consented indexa_session_id/indexa_lang cart attributes through checkout. No customer PII is stored. Revenue is paid merchandise after discounts, excluding tax/shipping; refunds and later edits are not adjusted in V1.
• • Send one object or an array of up to 20. The response comes back before the write: a beacon must not hold a page open while it navigates away.
• • event_type is one of view, click, add_to_cart, purchase. A missing key means view; a key that is present but not a string is rejected rather than coerced — junk filed under view would poison the most used signal in the table.
• • product_id must match ^[A-Za-z0-9_-]{1,64}$. Numbers are accepted and stringified. An unknown lang falls back to the store's default.
• • Content type is not checked: sendBeacon picks its own, and cannot retry a failed preflight.

Raw engine query. One or several searches per call.

X-TYPESENSE-API-KEY: $SEARCH_KEY — read-only, collection-scoped.

{
  "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
  }]
}

{ "results": [ { "found": 128, "hits": [ { "document": { "id": "7523891", "…": "…" } } ], "facet_counts": [] } ] }

Upserts or deletes one product across every language collection.

Signed by Shopify (X-Shopify-Hmac-Sha256) and verified against your webhook secret.

{ "received": true }

Keeps collection membership honest between reindexes — an edited smart-collection rule changes which products belong without touching any product.

Signed by Shopify (X-Shopify-Hmac-Sha256) and verified against your webhook secret.

{ "received": true }

Run a search the way a shopper would get it, without recording it, and get back what the engine did. This is what the console's playground calls.

Authorization: Bearer $ADMIN_KEY — server-side only.

{
  "hits": [ /* … */ ], "found": 5,
  "understood": { "sizes": ["XL"], "colors": ["Verde"], "genders": [] },
  "relaxed": { "terms": ["inverno"], "sizes": ["XL"] },
  "debug": {
    "searchTerm": "maglione",
    "queryBy": "title,vendor,model_code,sku,tags,primary_category",
    "weights": "6,3,4,4,2,2",
    "filters": ["available:true", "colors:=["Verde"]"],
    "rule": null,
    "attempts": [ { "found": 0, "filters": ["available:true", "sizes:=["XL"]", "colors:=["Verde"]"] } ],
    "tookMs": 62
  }
}

• • Never written to search_events. A merchant testing a phrase twenty times would otherwise invent a popular query and move the suggestions their own shoppers see.
• • debug exposes this store's configuration — effective weights, the merchandising rule matched — which is why it needs the admin key rather than being a flag on the public endpoint.
• • A malformed raw_filter comes back as 400 carrying the engine's own message (Could not find a filter field named \zzz\ in the schema) plus the expression you sent. The field is written by iterating, so the error has to be readable; every other failure is still a 500.

List Shopify collections, saved strategies, readiness and preparation progress.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "collections": [ /* {collection, strategy, revision, status} */ ], "prerequisites": { "ready": false, "issues": [] }, "sync": { /* preparation status and counts */ } }

• • Use the tenant TYPESENSE_ADMIN_API_KEY as ADMIN_KEY. Public search keys and storefront API keys are not accepted. JSON bodies are limited to 64 KiB.
• • Collection handles must match ^[a-z0-9][a-z0-9_-]{0,254}$. Read the current revision before saving or publishing. Errors use {error:{code,message}}: 400 invalid, 401 unauthorized, 409 preparation/revision/lease/drift conflicts, 413 payload_too_large, 503 unavailable.
• • Each collection has id, handle, title, sortOrder, productCount and automated. strategy is null and revision is 0 before the first save. Setup failures are explicit errors, not an empty collection list.

Prepare the tenant: reconcile webhooks, backfill paid orders, sweep inventory and update indexed stock.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "sync": { /* status, phase, started_at, completed_at, orders, products, error */ } }

• • Returns 202 while preparation runs asynchronously. Poll GET /admin/collections for sync progress. Completion requires status=succeeded and completed_at, plus ready prerequisites. Retry failed or interrupted runs; this does not enable or publish a strategy.
• • POST /admin/collections/sync is reserved for preparation; GET at that path reads a collection whose handle is sync.

Read a collection, saved strategy, revision, live preview and operational status.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "collection": { /* metadata and productIds */ }, "strategy": null, "revision": 0, "preview": null, "preview_error": { "code": "unavailable", "message": "Collection signals unavailable" }, "prerequisites": { "ready": false, "issues": [] }, "sync": { /* preparation state */ }, "status": "disabled" }

• • Illustrative unconfigured response. A successful preview is populated; if strict signals cannot be loaded it is null with preview_error. Collection status is disabled, preparation_required, ready_to_publish, published, unresolved, drift or restore_required.
• • preview includes collection, config, revision, currentIds, proposedIds, moves, changedProducts, ranking and products. products is keyed by ID with available presentation fields such as title and image_url, including unindexed Shopify members. ranking reports orderedIds, per-product scores/contributions/rules, signal coverage and unevaluatedIds. Compatible services also return preview.provenance: requestedMode and usedMode (rules or intelligence), nullable provider/modelKey/checkpointKey/featureSchemaVersion, latencyMs, comparisons, fallback, reason, candidateCount and rerankedCount. candidateCount counts indexed products in the bounded strategy window; rerankedCount counts products evaluated by the model, not changed positions. Rules scores describe candidate generation, not AI feature attribution.

Preview an unsaved configuration without saving it or changing Shopify.

Authorization: Bearer $ADMIN_KEY — server-side only.

{
  "config": {
    "enabled": false,
    "sorters": [
      {
        "param": "units_sold",
        "direction": "desc",
        "weight": 100
      }
    ],
    "lookback_days": 30,
    "depth": 200,
    "rules": {
      "push_down_tags": [],
      "push_up_tags": [],
      "new_days": 0,
      "unavailable_last": true,
      "pins": [],
      "tag_scores": {},
      "vendor_scores": {}
    }
  }
}

{ "preview": { /* collection, config, revision, currentIds, proposedIds, moves, changedProducts, ranking, products, provenance */ } }

• • Config fields: enabled (boolean), optional ranking_mode (rules or intelligence; defaults to rules when omitted; null/unknown values rejected), sorters (1–18 unique signals with direction asc/desc and weight 0–100; at least one positive), lookback_days (7 or 30), depth (1–20,000), and rules. Signal names: price, compare_at_price, discount_pct, days_since_published, units_sold, revenue, orders_count, views, add_to_cart, ctr, conversion_rate, revenue_per_view, inventory, in_stock_variants_ratio, days_to_sell_out, tag_score_adjust, vendor_score_adjust, random. Rules contain push_down_tags, push_up_tags, new_days, unavailable_last, pins ({id: numeric product ID string, position: one-based integer}), tag_scores and vendor_scores. Unknown fields are rejected.
• • The example is a disabled draft using units sold descending. Rules rank the complete collection. Intelligence only reranks a bounded leading window of at most 32 positions within depth, further limited by tenant topN and fixed/unindexed products. Exact pins, effective priority groups, membership and the remaining order survive reranking. A disabled draft can preview AI if tenant/deployment Intelligence is enabled. Missing strict signal data returns 503 rather than a fabricated score.
• • Successful Intelligence provenance can include productMovements: [{id, fromPosition, toPosition}], with one-based final constrained positions relative to the rules-only baseline. This is distinct from preview.moves/changedProducts, which compare against current Shopify order. Optional productEvidence contains [{id, wins, comparisons, opponents:[{id, preferred}], features:[{name, source, value}], salesLookbackDays}]. value is numeric or boolean; at most eight actual mapped inputs are exposed per evaluated product. wins/opponents describe observed tournament decisions, not causal feature importance. Evidence is admin-only and omitted on fallback; legacy services may omit provenance entirely. A successful inference can evaluate products without moving any of them.
• • Collection inference has a separate maximum 45-second deadline. Inspect usedMode and fallback rather than assuming requested Intelligence was used. Shopper inference remains bounded by at most 1,000 ms. On older services omit ranking_mode for Rules compatibility; Intelligence requires provenance support.

Save a strategy with revision checking. Disabled drafts do not reorder Shopify.

Authorization: Bearer $ADMIN_KEY — server-side only.

{
  "config": {
    "enabled": false,
    "sorters": [
      {
        "param": "units_sold",
        "direction": "desc",
        "weight": 100
      }
    ],
    "lookback_days": 30,
    "depth": 200,
    "rules": {
      "push_down_tags": [],
      "push_up_tags": [],
      "new_days": 0,
      "unavailable_last": true,
      "pins": [],
      "tag_scores": {},
      "vendor_scores": {}
    }
  },
  "revision": 0
}

{ "strategy": { /* saved config and publication journal */ }, "revision": 1, "status": "disabled" }

• • Use revision 0 only for the first save; subsequently use the revision from detail/save. A stale revision returns 409.
• • Enabling requires successful data preparation and current prerequisites. An enabled strategy opts into scheduled and event-driven publication; save is not an immediate publish command. The config accepts the same ranking_mode as preview. Saving a disabled Intelligence draft neither enables tenant AI nor changes Shopify order.

Publish the saved strategy to Shopify using the expected revision.

Authorization: Bearer $ADMIN_KEY — server-side only.

{
  "revision": 1
}

{ "status": "published", "changedProducts": 3, "strategy": { /* saved config and publication journal */ } }

• • Requires the current saved revision. Enabled publication needs successful preparation and prerequisites. Optional minChangedProducts is an integer from 1 to 20,000.
• • May return status=skipped with reason disabled, unchanged or below_threshold. First publication captures the original baseline and switches Shopify sort mode to MANUAL. Order is shared across markets. Drift or an unresolved mutation blocks automatic overwrite. Intelligence mode requires fresh successful Intelligence inference, including after sort/membership recomputation; fallback blocks publication. Preview is not a frozen publication snapshot. Successful publication stores provenance in strategy.last_ranking; restoring the baseline clears it.

Restore the captured original Shopify order and sort mode, then disable the strategy.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "status": "restored", "strategy": { /* disabled strategy and updated journal */ } }

• • Send no body or an empty JSON object. Restore is explicit and does not require a new successful preparation. It needs the captured original baseline and access to Shopify/storage. Retry an interrupted restore to reconcile its state; do not force another publication.

Full reindex of every language, run asynchronously.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "started": true }

Mint a fresh read-only engine key, scoped to your collections.

Authorization: Bearer $ADMIN_KEY — server-side only.

{ "search_key": "…" }

Liveness, and the languages this indexer serves.

{ "ok": true, "languages": ["it", "en"] }