Getting started guide — from sign-up to full setup

Three steps to get working search. Then three independent modules, to activate as needed — none is required for the engine to answer your customers.

Step 1 — Sign up

Choose a plan on the pricing page — the 14-day trial requires no credit card. Once you've signed up, your API key (hx_...) is immediately available in your console, under "My info."

[Screenshot to add: the API key shown in the console, My info section]

Step 2 — Index your first catalog

One call is enough — the catalog is created automatically on first import, no prior setup needed:

curl -X POST https://api.heurix.fr/v1/index/mycatalog/items   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
  "items": [
    {"id": "sku-1", "name": "BOSCH GDX 18V-285 Drill", "ref": "M8 x 20 - Stainless A2", "stock": 8, "price": 139.90}
  ]
}'

Specify "rulepack": "outillage" in the request body if your industry matches one of the ten pre-configured rule packs — otherwise, the engine still indexes, with more limited structure recognition until a pack or Custom Rule is active.

Step 3 — Confirm search works

curl -X POST https://api.heurix.fr/v1/index/mycatalog/search   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"q": "bosch drill"}'

A response with your product in hits confirms everything works. At this point, search is fully operational — everything below is optional.

[Screenshot to add: the console's "Overview" dashboard once the first catalog is indexed]

Build your own path

Three questions to keep only what's relevant to you. Steps 1 to 3 above are required either way.

Do you want to measure the sales search generates?

Do your teams need to query the catalog through an AI agent?

Do you already have a search interface on your site?

From here, three independent modules

🔑 Two of the three modules run in the browser (Tracker and front-end integration). First generate a public key from your console (My info → My API key): it starts with hxp_ and can only search, browse, and report events. Your server key (hx_) should never appear in a web page — it grants access to your billing. Details on both key types.

Each answers a different need. Activate what's relevant to you, ignore the rest — nothing is required for the other two, and nothing is required for search itself to keep working.

Optional module — Heurix Tracker (Conversion & ROI)

To find out which searches actually generate sales, not just clicks. Download heurix-tracker.js, edit the two variables at the top of the file with your key and your catalog:

var HEURIX_API_KEY = "YOUR_PUBLIC_KEY";  // hxp_, not hx_
var HEURIX_CATALOG = "mycatalog";

Then drop the script once, site-wide:

<script src="heurix-tracker.js"></script>

Then call Heurix.trackClick(query, productId) on a click from your search results, and Heurix.trackPurchase([{id, amount, margin}]) when an order is confirmed — full details in the Conversion & ROI documentation.

[Screenshot to add: the console's Conversion & ROI panel with initial data]

Optional module — Front-end integration

Two ways to display search on your site, depending on your situation:

You're starting from scratch, no existing search — heurix-search.js, a standalone script that renders a full search bar (input, results, facets) in three lines:

<div id="my-search"></div>
<script src="heurix-search.js?v=1785453013"></script>
<script>
  Heurix.searchBox({ apiKey: "YOUR_PUBLIC_KEY", catalog: "mycatalog", containerId: "my-search" });
</script>

You already have an interface, or an established JS/TS stack — heurix-client, a lightweight client to build your own interface:

npm install heurix-client

import { HeurixClient } from "heurix-client";
const client = new HeurixClient({ apiKey: "YOUR_API_KEY", catalog: "mycatalog" });
const results = await client.search("bosch drill");

Full details on both options: heurix-search.js and the API reference to build your own call.

[Screenshot to add: heurix-search.js in action on a test page, results shown]

Optional module — MCP server (AI agents)

So an AI agent (Claude Desktop, Cursor, an internal agent) can query your catalog in natural language, without ever calling the API itself. Full guide, step-by-step install included: Connecting Heurix to Claude Desktop and Cursor.

What's next

Once these basics are in place, the full documentation covers the rest — synonyms, facets, Browse & Discovery, query priorities. None of it is required to get started, but all of it is available whenever you need it.