Overview

Luigi’s Box AI is product discovery for online retail: search, category listings and recommendations that learn from how shoppers behave, plus the merchandising controls to override them when you need to.

There are four things you integrate with, and they fit together in one loop.

Step	You do	Luigi’s Box does
1. Index	Send your catalog, as a feed or over the API	Makes it searchable
2. Discover	Ask a surface for results	Ranks and returns them
3. Report	Report clicks, cart additions and purchases	Learns from them, and reports
4. Merchandise	Pin, ban, boost and bury	Applies it inside ranking

Ranking improves from behaviour, so an integration that indexes and searches but never reports what shoppers did gets a static search engine.

You do not report what was shown — the results a surface returned are recorded when the request is served. Only what happened next is yours to send.

The shape of it

What shoppers do with the results feeds back into how the next request is ranked.

Vocabulary you need on day one

Four terms appear in nearly every request. The domain model has the whole picture; this is the minimum.

Term	Meaning	Looks like
Catalog	One set of objects in one language	lbc_8w3k2p
Channel	A storefront or market — a view over a catalog	lbn_4hj9tv
Surface	A configured discovery experience you call	lbs_search_main
Object	A product, category, brand or article	product/sku-1001

You index objects into a catalog, and your storefront asks a surface for results on a channel.

Choosing your path

Start with a distribution repository

This is the default, and the fastest way to a working storefront. Luigi’s Box hosts a git repository for your integration, pre-seeded with a working scaffold and a pack of skills written for coding agents. You create it, clone it, tell your agent to integrate your site, and review the result on a preview URL against your real pages.

The skill pack covers the search box, the facet sidebar and the analytics wiring; the repository holds the decisions specific to your site.

→ Distribution · Your first integration

Or call the API yourself

Use this instead when your storefront renders results server-side, when discovery results will be rendered by your own component library, or when what you are integrating is not a website.

From the browser	Your storefront’s JavaScript calls Luigi’s Box directly. Lowest latency, no traffic through your own servers. Needs a publishable key — safe to ship in page source, bound to one channel and to the origins you register. → Browser quickstart
From your backend	Your server calls Luigi’s Box and renders results server-side, or runs indexing and configuration jobs. Needs an OAuth client ID and secret, kept server-side. → Backend quickstart

These are not exclusive, and neither is the choice above. The common shape is a distribution repository for the storefront and a backend integration for indexing and configuration — the catalog and the credentials are the same either way.

Or click it together

Creating the integration repository, adding channels and running merchandising campaigns are all available in the Hub, the browser console for your account. Pages here carry an In the Hub panel wherever the call they describe has a form there.

Getting your catalog in

Two ways in, each complete on its own. Pick the one matching how your platform already works.

	Content API	Feeds
You provide	HTTP calls	A file at a stable URL
Model	Objects and changes, as they happen	Full snapshot
Freshness	Seconds	Checked every 60 seconds
Deletions	You send them	Absent from the snapshot
Fits when	Your platform can emit what changed	Your platform already produces exports

Push over the Content API if you can. One path owns the whole catalog, changes are searchable in seconds, and there is nothing to reconcile between sources. Use a feed if your platform already exports catalog files and you would rather not build a push integration — it is a complete way to run a catalog too.

Do not split one object type across both. A feed run sends the whole object and overwrites whatever the API last set, so mixed ownership makes the state of a catalog hard to establish.

Either way, field mapping means your data keeps its own field names and shapes. You do not restructure it to fit ours.

A first integration, in order

1. Get credentials. A publishable key for the browser, an OAuth client for your backend, and the IDs of your catalog and channel. → Authentication
2. Get the catalog in. Register a feed, or push objects. Confirm the first run succeeded and the fields are typed as you expect. → Feeds · Catalog metadata
3. Make one search request. One curl POSTing to /discovery/v1/search with your channel and surface. → Search
4. Wire the storefront. A distribution repository and an agent, or your own code. → Your first integration · Browser quickstart
5. Report behaviour. Clicks, cart additions and purchases — from the first day, not after launch. A distribution repository wires this for you. → Sending events
6. Add business rules, once there is traffic. Pins and bans for the cases ranking cannot know about. → Business rules

Do steps 2 and 3 before writing any storefront code, and before pointing an agent at a repository — it has nothing to build against until the catalog is there.

How this documentation is organized

Section	For
Distribution	The managed integration repository — the default way to build a storefront
Core concepts	The mental model — entities, identifiers, object shape
Authentication	Credentials and tokens
API basics	Conventions every endpoint shares
Indexing	Getting your catalog in and keeping it fresh
Discovery	Search, listings, recommendations, facets, filters
Merchandising	Overriding ranking — business rules, and sponsored placements
Analytics	Sending events, and reporting on them
Platform	Managing catalogs, channels, surfaces and tags
API Reference	Every endpoint, generated from the API contract — download it and generate a client

Regions

Luigi’s Box AI runs in independent regions, and your account lives in one of them. Two hosts:

https://auth.<region>.luigisbox.ai   getting a token
https://api.<region>.luigisbox.ai    everything else

Examples throughout these docs use eu1. Substitute your own region — your credentials carry it in their own value.

See also

• Your first integration — the default path
• Browser quickstart · Backend quickstart
• Domain model · Identifiers
• Discovery overview