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.

Foundations

Required

Sign-up · API key · first catalog indexed

Heurix Tracker

Optional

Conversion tracking — clicks and purchases tied to a search

Front-end integration

Optional

A ready-to-use search bar for your site

MCP server

Optional

Connect Heurix directly to an AI agent

Step 1 — Sign up

Create your account from the console: the 14-day free trial requires no credit card. Your API key (hx_...) is immediately available in your console, under My account → API key. A paid plan is subscribed to afterwards on the pricing page.

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 eleven 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.

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 account → 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.

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"></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.

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. What to watch each week, and which lever to try first: running your search day to day.