Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.
Search the catalog
const url = 'https://api.eu1.luigisbox.ai/discovery/v1/search?channel_id=example&surface_id=example&user_id=&personalize=false&filters=&size=10&mode=&debug=false&type=example&query=&sort=&cursor=';const options = { method: 'GET', headers: { 'x-lbx-visitor-id': 'example', 'user-agent': '', referer: '', Authorization: 'Bearer <token>' }};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.eu1.luigisbox.ai/discovery/v1/search?channel_id=example&surface_id=example&user_id=&personalize=false&filters=&size=10&mode=&debug=false&type=example&query=&sort=&cursor=' \ --header 'Authorization: Bearer <token>' \ --header 'referer: ' \ --header 'user-agent: ' \ --header 'x-lbx-visitor-id: example'Full-text search over the catalog.
Rate limited: a 429 carries Retry-After.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Channel identifier (serving destination).
Channel identifier (serving destination).
Surface identifier, lbs_
Surface identifier, lbs_
Logged-in user identifier. Optional; omitted/blank values are treated as anonymous.
Logged-in user identifier. Optional; omitted/blank values are treated as anonymous.
Whether to apply personalization.
Whether to apply personalization.
Filter expression, for example ‘brand = nike AND lbx:price < 100’.
Filter expression, for example ‘brand = nike AND lbx:price < 100’.
Field projection list. Each entry is either '' (alone, all fields) or a field path, optionally ending in '' to take a whole subtree (e.g. ‘attributes.title’ or ‘attributes.’). '' cannot be combined with other names.
Field projection list. Each entry is either '' (alone, all fields) or a field path, optionally ending in '' to take a whole subtree (e.g. ‘attributes.title’ or ‘attributes.’). '' cannot be combined with other names.
Maximum number of items to return. Must be between 1 and 100.
Maximum number of items to return. Must be between 1 and 100.
Special mode flag; ‘mock’ returns a canned response.
Special mode flag; ‘mock’ returns a canned response.
Request ranking diagnostics. Honoured only on the first page for callers holding discovery:debug; silently ignored otherwise.
Request ranking diagnostics. Honoured only on the first page for callers holding discovery:debug; silently ignored otherwise.
Object type to retrieve (e.g. ‘product’, ‘category’, ‘article’).
Object type to retrieve (e.g. ‘product’, ‘category’, ‘article’).
User input search query.
User input search query.
Sort expression, e.g. ‘price:asc’.
Sort expression, e.g. ‘price:asc’.
Opaque pagination cursor returned by a previous response.
Opaque pagination cursor returned by a previous response.
Header Parameters
Section titled “Header Parameters ”Stable per-browser visitor identifier, generated client-side and persisted (e.g. a UUID in localStorage or a first-party cookie). Send it whether or not personalization is on: it is what links a request to a visitor’s history and to the analytics events reporting it. Keep it stable across page loads, sessions and token refreshes; never generate it server-side, or every visitor collapses into one.
Stable per-browser visitor identifier, generated client-side and persisted (e.g. a UUID in localStorage or a first-party cookie). Send it whether or not personalization is on: it is what links a request to a visitor’s history and to the analytics events reporting it. Keep it stable across page loads, sessions and token refreshes; never generate it server-side, or every visitor collapses into one.
Originating client’s User-Agent. Optional; used to derive the platform (ios, android, web) the result set is attributed to. A backend caller should forward the end user’s value rather than its own.
Originating client’s User-Agent. Optional; used to derive the platform (ios, android, web) the result set is attributed to. A backend caller should forward the end user’s value rather than its own.
Originating page URL. Optional; lets the result set be attributed to the page it was served on.
Originating page URL. Optional; lets the result set be attributed to the page it was served on.
Responses
Section titled “ Responses ”Successful Response
Response of the search endpoint.
object
GUID identifying this result set.
Ranked list of result hits — only objects this channel can serve.
Single result item returned by discover endpoints.
Flat structure — all catalog fields are top-level keys.
@id and @type are always present; every other key is a catalog field.
object
Unique identity of the hit.
Type of the hit (e.g. ‘product’).
Why this response does or does not carry a next_page_cursor: more — more pages exist and next_page_cursor is set; exhausted — this was the last page; unsupported — this result set cannot be paged and retrying will not produce a cursor; unavailable — pagination state could not be saved for this request (a transient failure) and re-issuing the search may succeed.
Approximate total for the whole result set, counting only the objects this channel can serve. Always present, so use it as the fallback when total is null. It may be an estimate, so prefer total wherever that is set.
Example
{ "pagination_status": "more"}Malformed request
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Missing or invalid credentials
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Authenticated but not permitted
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Resource not found
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Request validation failed
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Rate limit exceeded
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Upstream service failed
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
One field-level reason a request was rejected.
object
Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].
What is wrong with the value at loc.
Stable machine code for the problem, e.g. missing or string_too_short.
Human-readable, actionable error message.
Example generated
{ "exception_details": { "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Was this page helpful?
Thanks.