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.
Compute facets for a result set
const url = 'https://api.eu1.luigisbox.ai/discovery/v1/facets?channel_id=example&guid=example&facet_fields=example&debug=false';const options = {method: 'GET', headers: {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/facets?channel_id=example&guid=example&facet_fields=example&debug=false' \ --header 'Authorization: Bearer <token>'Compute facets for a previously executed search or listing.
Rate limited: a 429 carries Retry-After.
Facets are computed over the result set identified by guid: per-field
values for a keyword field, min/max bounds for a numeric one.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Channel identifier (serving destination).
Channel identifier (serving destination).
GUID from a prior /search or /collection response to facet on.
GUID from a prior /search or /collection response to facet on.
Comma-separated facet fields. Each entry is a plain field name or ‘name^count’ where count limits the number of returned keyword facet values (positive integer). Use ’^’ for namespaced fields, e.g. ‘lbx:price^30’. The ‘name:count’ form is also accepted.
Comma-separated facet fields. Each entry is a plain field name or ‘name^count’ where count limits the number of returned keyword facet values (positive integer). Use ’^’ for namespaced fields, e.g. ‘lbx:price^30’. The ‘name:count’ form is also accepted.
Open branches to expand in hierarchical facets. Each value is ’
Open branches to expand in hierarchical facets. Each value is ’
Requested child-level expansion for hierarchical facets. Each value is ’
Requested child-level expansion for hierarchical facets. Each value is ’
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.
Responses
Section titled “ Responses ”Successful Response
Response of the facets endpoint.
object
Per-field facet aggregation results. Values, bounds and counts cover only the objects this channel can serve.
object
Terms facet — distinct values for a categorical field.
object
The faceted field name.
Range facet — min/max bounds for a numeric field.
object
The faceted field name.
Maximum value in the result set.
Minimum value in the result set.
Hierarchy facet — a tree of nodes for a hierarchical field.
object
The faceted field name.
A single node of a hierarchy facet tree.
object
Whether the node has expandable descendants.
Display title of the node’s own identity.
Fully expanded node path (segments joined by ’ > ’).
Deprecated alias of request_key carrying the same value. Read request_key instead: guid will be repurposed as the per-request attribution identifier once clients have migrated.
Key derived from the request parameters that decide which objects are returned. Two identical requests produce the same value. A request with personalize set to true and no explicit sort is also scoped to its shopper (user_id and X-Lbx-Visitor-Id), so two visitors sending it get different values; every other request keys the same for every shopper. Pass it to /facets and /variants to address the same result set; a cursor is only valid together with the request key it was issued for.
Example
{ "facets": { "additionalProperty": { "type": "terms" } }}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
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "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
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "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
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "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
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Request validation failed
The canonical error body of a Discovery 422, with error_code typed.
Every key of the envelope is required, as the served body always carries all three.
object
Machine-readable error context; empty object when there is nothing to add.
object
exception_details.error_code values for a rejected cursor.
Clients switch on these to drop the cursor and request page 1; the reason beside them is for humans and may be reworded.
exception_details.error_code values for a request that names the wrong surface.
exception_details.error_code values for a touchpoint the endpoint cannot record.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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
{ "exception_details": { "error_code": "filter_syntax" }}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
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Service temporarily unavailable
Canonical error body — every non-2xx response uses this shape.
object
Machine-readable error context; empty object when there is nothing to add.
object
Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.
Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.
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": { "error_code": "example", "validation_errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ] }, "reason": "example", "request_id": "example"}Was this page helpful?
Thanks.