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.
Create a collection
const url = 'https://api.eu1.luigisbox.ai/platform/v1/catalogs/example/collections';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"ancestry_attribute":"lbx:category_ids","collection_type":"category","kind":"membership","member_type":"product","membership_attribute":"lbx:category_ids"}'};
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/platform/v1/catalogs/example/collections \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ancestry_attribute": "lbx:category_ids", "collection_type": "category", "kind": "membership", "member_type": "product", "membership_attribute": "lbx:category_ids" }'Register a membership collection (one per collection_type and member_type pair) or a curated collection (one per slug and member_type). The id is built from those fields and returned; a second registration of the same id is a 409. A catalog holds at most 1000 collections. Types and attributes are checked against the ones the catalog has ingested. Filter trees are normalised before they are stored — a negative leaf gains an exists on its field beside it (see filters) — so the resource this returns can differ from the body sent. The response carries the stored form.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
Catalog object type whose objects are the collections, e.g. category. It must exist in the catalog; curated and all are reserved.
membership: every object of collection_type is a collection of the member objects that reference it through membership_attribute.
Catalog object type the collection returns. It must exist in the catalog.
Attribute of the member type holding the @id of every collection object the member belongs to, e.g. lbx:category_ids, which holds every category an object is in and every category above them. It must exist on the member type; @-prefixed attributes skip that check. The private:, signals:, ml: and lexical: namespaces are refused.
object
A group node: exactly one of $and, $or, $not.
object
A condition node: field names mapped to operator objects; sibling fields combine as AND.
object
Operators applied to one field. Several operators in one object combine as AND.
object
curated: one named filter over the member type.
Catalog object type the collection returns. It must exist in the catalog.
Human-readable name, for display. It takes no part in the id and cannot be changed.
Id segment of your choice: lowercase ASCII letters, digits, _ and -, up to 256 characters. The collection id is collection:curated/{slug}/member:{member_type}, so one slug registers one collection per member type. It cannot be changed.
Responses
Section titled “ Responses ”Successful Response
object
Catalog the collection belongs to.
Catalog object type whose objects are the collections, e.g. category. It must exist in the catalog; curated and all are reserved.
When the collection was registered.
Collection id, built from the registration. A membership collection is collection:{collection_type}/member:{member_type}; a request serves one of its objects as collection:{@id}/member:{member_type}. A curated collection is collection:curated/{slug}/member:{member_type}, and a request serves it by this id.
membership: every object of collection_type is a collection of the member objects that reference it through membership_attribute.
Catalog object type the collection returns. It must exist in the catalog.
Attribute of the member type holding the @id of every collection object the member belongs to.
When the collection was last changed; its registration time until then.
object
Catalog the collection belongs to.
When the collection was registered.
A group node: exactly one of $and, $or, $not.
object
Nodes that must all match.
A condition node: field names mapped to operator objects; sibling fields combine as AND.
object
Operators applied to one field. Several operators in one object combine as AND.
object
A condition node: field names mapped to operator objects; sibling fields combine as AND.
object
Operators applied to one field. Several operators in one object combine as AND.
object
Nodes of which at least one must match.
A condition node: field names mapped to operator objects; sibling fields combine as AND.
object
Operators applied to one field. Several operators in one object combine as AND.
object
A condition node: field names mapped to operator objects; sibling fields combine as AND.
object
Operators applied to one field. Several operators in one object combine as AND.
object
Collection id, built from the registration. A membership collection is collection:{collection_type}/member:{member_type}; a request serves one of its objects as collection:{@id}/member:{member_type}. A curated collection is collection:curated/{slug}/member:{member_type}, and a request serves it by this id.
curated: one named filter over the member type.
Catalog object type the collection returns. It must exist in the catalog.
Human-readable name, for display. It takes no part in the id and cannot be changed.
Id segment chosen at registration.
When the collection was last changed; its registration time until then.
Example
{ "id": "collection:category/member:product", "kind": "membership"}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"}State conflict
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
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"}The catalog’s types could not be read, so the collection could not be checked against them. Retryable: Retry-After carries the number of seconds to wait.
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"}Headers
Section titled “Headers ”Seconds to wait before retrying the write.
Was this page helpful?
Thanks.