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 result facets
const url = 'https://api.eu1.luigisbox.ai/discovery/v1/facets?channel_id=example';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"debug":false,"facets":[{"field":"example","size":1}],"guid":"example","hierarchy_anchors":[{"field":"example","path":"example"}],"hierarchy_depths":[{"depth":1,"field":"example"}],"request_key":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.eu1.luigisbox.ai/discovery/v1/facets?channel_id=example' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "debug": false, "facets": [ { "field": "example", "size": 1 } ], "guid": "example", "hierarchy_anchors": [ { "field": "example", "path": "example" } ], "hierarchy_depths": [ { "depth": 1, "field": "example" } ], "request_key": "example" }'Compute facets from a structured JSON request body.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Channel identifier (serving destination).
Channel identifier (serving destination).
Request Body required
Section titled “Request Body required ”JSON body accepted by the facets endpoint.
object
Include a diagnostic debug payload in the response.
Explicitly opened branches whose children should be expanded in a hierarchy facet.
One explicitly opened branch in a hierarchy facet.
object
Hierarchical facet field the anchor applies to.
Node path whose children to expand, as the ’ > ‘-joined string stored in the field.
Per-field child-level expansion depth for hierarchy facets; each field may appear at most once.
Requested child-level expansion for one hierarchical facet field.
object
Number of child levels to expand from the roots.
Hierarchical facet field the depth applies to.
JSON body accepted by the facets endpoint.
object
Include a diagnostic debug payload in the response.
Explicitly opened branches whose children should be expanded in a hierarchy facet.
One explicitly opened branch in a hierarchy facet.
object
Hierarchical facet field the anchor applies to.
Node path whose children to expand, as the ’ > ‘-joined string stored in the field.
Per-field child-level expansion depth for hierarchy facets; each field may appear at most once.
Requested child-level expansion for one hierarchical facet field.
object
Number of child levels to expand from the roots.
Hierarchical facet field the depth applies to.
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.