Identifiers

Almost every API call names at least one identifier. Luigi’s Box AI uses prefixed IDs: the prefix says what a value refers to, and a value pasted into the wrong parameter is rejected.

Account identifiers

These are assigned by Luigi’s Box when the entity is created. You never invent them.

Entity	Prefix	Example	Where you use it
Organization	lbo_	lbo_r2vn8c	Scoping list endpoints, creating catalogs
Catalog	lbc_	lbc_8w3k2p	Indexing, feed configuration, catalog metadata
Channel	lbn_	lbn_4hj9tv	Every discovery request, every analytics event
Campaign	lbm_	lbm_p7q2zx	Business rules
Rule	lbr_	lbr_2m8xkd	Business rules
A/B test	lba_	lba_9v3npc	Experiment reporting
Tag	lbt_	lbt_k4d7rq	Grouping catalogs, channels or surfaces
Sponsored-products provider	lbad_	lbad_9v3npc	Sponsored products
Integration repository	lbdr_	lbdr_8w3k2p	Distribution

The prefix is part of the value. Store and send lbc_8w3k2p, never 8w3k2p.

Shape

An account identifier is a prefix, an underscore, and six characters from Crockford base32 — the digits 0–9 plus the letters a–z with i, l, o and u left out. The canonical form is lowercase.

Input is forgiving: uppercase is accepted, hyphens are ignored, and i/l are read as 1 and o as 0. LBC-8W3K2P and lbc_8w3k2p name the same catalog.

Note

IDs never change. Renaming a catalog or a channel keeps its identifier, because access grants and analytics history are attached to the ID, not the name.

Record identifiers

Some identifiers name a record Luigi’s Box writes rather than an entity you set up: one synchronization run of a feed is one. Records accumulate without limit, so their identifiers are longer.

Record	Prefix	Example	Where you see it
Feed sync run	lbsr_	lbsr_7k2m9xq4vd	Run history
Catalog sync	lbsy_	lbsy_4n8w2c6t0q	Triggering a sync

A record identifier is a prefix, an underscore, and ten characters from the same Crockford base32 alphabet, in lowercase. It is random: it says nothing about when the record was written or how many came before it.

lbsr_7k2m9xq4vd, lbsy_4n8w2c6t0q and lbs_search_main are unrelated: the underscore ends the prefix, so neither lbsr nor lbsy is a surface.

Surface identifiers

A surface is the configured discovery experience your storefront calls. Its ID has three parts:

lbs_<intent>_<slug>

• lbs — always.
• <intent> — what kind of discovery the surface performs: search, recommender, or collection.
• <slug> — a readable name chosen when the surface is created: lowercase letters, digits and underscores, starting with a letter, up to 48 characters.

lbs_search_main
lbs_recommender_similar
lbs_collection_default

The intent in the ID says which endpoint the surface belongs to. Sending lbs_recommender_similar to /discovery/v1/search is rejected, because the intent in the ID does not match the endpoint.

Slugs are unique within one catalog and intent, so the same catalog cannot have two lbs_search_main surfaces — but two different catalogs can.

Collection identifiers

A membership or curated collection’s ID is built from its registration, so you know it before registering. For a membership collection it is the two types; for a curated collection it is the slug you send and the member type. An all collection is not registered at all: its ID exists for every type. The member type is part of the ID, where search and recommendation requests take a type beside it, so one value names everything a collection request lists.

Kind	Registered as	A request names
Membership	collection:category/member:product	one object of it: collection:category/shirts/member:product
Curated	collection:curated/new_arrivals/member:product	the same ID
All	nothing	collection:all/member:category

The ID contains / and is sent in a path as is. See Collections.

Catalog object identity

Catalog objects — products, categories, brands, articles — are identified by values you choose, not by Luigi’s Box. An identity is typed:

<type>/<value>

For example:

product/sku-1001
category/summer-shirts
brand/northwear

The type prefix must match the object’s @type. The value part is yours: a SKU, a slug, a database key. It only has to be unique within the catalog and stable over the object’s lifetime.

The same <type>/<value> form is used everywhere an object is referenced — in @id, in @category and @brand references, in the reference field of analytics events, and in ids sent to the variants endpoint.

Identity must be stable

Reusing or changing an object’s identity breaks the link between the object and its analytics history, ranking signals and recommendations. If a product’s key changes in your system, treat it as a delete plus a create — and expect its learned signals to start over.

See Types and IDs for the ingestion rules, and Object types and relationships for what each type is for.

Credentials

Credentials are not entity identifiers, and they have their own formats.

Credential	Prefix	Used by
Publishable key	pub_	Browser integrations — safe to ship in page source
OAuth client ID	lbk_	Server-to-server integrations
OAuth client secret	lbe_	Server-to-server integrations — secret, never in a browser

Both parts of a credential carry the environment and region they belong to, so a test key cannot accidentally authenticate against production, and a European client cannot authenticate in the US region. See Authentication.

See also

• Domain model — what these entities are and how they relate
• Catalog object model — the shape of an indexed object
• Requests and responses — where each identifier goes in a call