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.
Get a campaign
const url = 'https://api.eu1.luigisbox.ai/platform/v1/campaigns/example?filter_syntax=group';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/platform/v1/campaigns/example?filter_syntax=group' \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Query Parameters
Section titled “Query Parameters ”Syntax filter trees are rendered in. group is the {operator, conditions} form; map is the $and / $or / $not map syntax the Discovery API uses, in which an empty tree renders as null. Request bodies accept either syntax regardless of this setting.
Syntax filter trees are rendered in. group is the {operator, conditions} form; map is the $and / $or / $not map syntax the Discovery API uses, in which an empty tree renders as null. Request bodies accept either syntax regardless of this setting.
Responses
Section titled “ Responses ”Successful Response
Campaign response: the explicit picks the merchandiser made, round-trippable into an update.
The effective scope — those picks unioned with the current members of the picked tags —
is not here; read it from
GET /platform/v1/campaigns/{campaign_id}/effective-scope. See CampaignEffectiveScope.
object
Catalogs this campaign narrows to, by id. catalog_tags narrows the same axis by contributing its members, so the scope is the union of the two. An axis nothing narrows is an axis the campaign does not restrict, so empty means every one of them rather than none. A catalog outside the organization is rejected with catalog_not_in_organization.
Catalog tags whose members join catalog_ids on the catalog axis. Resolved at read time, so editing a tag reflows into every campaign referencing it. A tag that does not exist in the organization is rejected with tag_not_found, and one carrying another dimension with tag_dimension_mismatch.
Channels this campaign narrows to, by id, jointly with channel_tags. An axis nothing narrows is an axis the campaign does not restrict, so empty means every one of them rather than none. Narrowing by channel requires a catalog scope (catalog_scope_required), the channel must be in the organization (channel_not_in_organization) and owned by a scoped catalog (channel_outside_catalog_scope).
Channel tags whose members join channel_ids on the channel axis, under the same resolution and the same tag_not_found / tag_dimension_mismatch rejections.
How this campaign’s placements are disclosed to shoppers.
Every product the campaign’s rules pin or boost carries it as the served hit’s
@disclosure object, together with the recipient_parameters derived from the
campaign; a boosted product’s also name the request’s own context.
object
The person or company on whose behalf the placement is shown, e.g. Northwear Ltd. At most 128 characters. A control character, invisible mark or bidirectional override is rejected with the validation error type disclosure_name_unprintable.
Who paid for the placement. Rejected with the validation error type disclosure_payer_requires_advertiser without an advertiser. At most 128 characters.
How the placement is disclosed. sponsored declares a paid placement.
Surface Intents this campaign targets — the kind of discovery it applies to. Empty means every Intent, not none. Narrowing by Intent is mutually exclusive with narrowing by surface_ids / surface_tags: an Intent targets whole families of surfaces, so combining the two is rejected with intents_conflict. A targeted Intent no scoped catalog hosts a surface for is rejected with catalog_without_targeted_intent — it could never trigger.
A filter tree in group syntax: a boolean operator over leaves and nested groups.
not holds exactly one child. An empty and constrains nothing and an
empty or matches nothing; each endpoint says whether it accepts either.
object
Leaf conditions and nested groups.
One leaf of a group-syntax tree: a field compared against a value.
object
Object field the condition reads.
What a condition reading its value from the request’s anchors does when none carries the attribute.
fail_closed (the default) makes the whole filter tree match nothing. ignore
drops the condition instead, leaving the rest of the tree in force.
Comparison operator.
Provenance of the condition; stamped by the system, never read from a client.
Literal to compare against, or a trigger reference {trigger_ref: ...}; a scalar for eq/neq and the comparisons, a non-empty list for in/not_in, absent for exists.
Where a dynamic condition reads its value: an attribute of the request’s anchors.
object
Anchor attribute whose value the condition compares against.
Boolean combinator applied to conditions.
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 value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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 value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
The array’s order is the campaign’s rule order and is stored as sent. Between two rules of one campaign competing for the same product, the one listed first wins, so re-sending the same rules in a different order re-orders the campaign.
object
Pin the selected product to a fixed 1-indexed position.
mode='soft' is the Soft Pin: the placement decays over decay_window.
respect_user_filters is live: an id-naming pin carrying False — the default
— has its product exempted from the shopper’s own post-filter.
Exclude the selected product(s) from results entirely.
object
Raise matching products in the ranking. strength_pct (0–1) scales how far.
A filter tree in group syntax: a boolean operator over leaves and nested groups.
not holds exactly one child. An empty and constrains nothing and an
empty or matches nothing; each endpoint says whether it accepts either.
object
Leaf conditions and nested groups.
One leaf of a group-syntax tree: a field compared against a value.
object
Object field the condition reads.
What a condition reading its value from the request’s anchors does when none carries the attribute.
fail_closed (the default) makes the whole filter tree match nothing. ignore
drops the condition instead, leaving the rest of the tree in force.
Comparison operator.
Provenance of the condition; stamped by the system, never read from a client.
Literal to compare against, or a trigger reference {trigger_ref: ...}; a scalar for eq/neq and the comparisons, a non-empty list for in/not_in, absent for exists.
Where a dynamic condition reads its value: an attribute of the request’s anchors.
object
Anchor attribute whose value the condition compares against.
Boolean combinator applied to conditions.
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 value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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 value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
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
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
A value resolved from the request’s trigger attributes at evaluation time.
object
Lifecycle state of a Campaign.
Surfaces this campaign narrows to, by id, jointly with surface_tags. An axis nothing narrows is an axis the campaign does not restrict, so empty means every one of them rather than none. Mutually exclusive with intents (intents_conflict), requires a catalog scope (catalog_scope_required), and each surface must sit under a scoped catalog (surface_not_in_catalog_scope).
Surface tags whose members join surface_ids on the surface axis, under the same resolution and rejections. A member whose own catalog is outside the catalog scope is tolerated rather than rejected, which keeps a surface tag reusable across catalogs.
IANA timezone identifier (e.g. Europe/Bratislava) the schedule was authored in, kept so it can be re-opened in that zone. Informational only: starts_at / ends_at are the UTC instants that govern when the campaign runs, and this field never shifts them — use it when re-planning a schedule, never to compute execution times. Requires at least one of starts_at / ends_at, and is cleared when both are cleared. Because tz databases differ between releases and between server and browser (Europe/Kiev vs Europe/Kyiv), a client whose own database does not know the identifier should keep the string as it is rather than discard or rewrite it. A scheduled campaign always reads back a zone — UTC when none was authored; an unscheduled one omits the field, so a response never shows the zone-without-schedule state that writes reject.
Example
{ "disclosure": { "type": "sponsored" }, "intents": [ "search" ], "match": { "$and": [ { "brand": { "in": [ "nike", "adidas" ] } }, { "lbx:price": { "gte": 50, "lte": 200 } }, { "$or": [ { "condition": { "eq": "new" } }, { "warranty_months": { "gte": 12 } } ] }, { "$not": { "material": { "eq": "leather" } } }, { "image": { "exists": true } } ] }, "rules": [ { "effect": { "mode": "hard", "respect_user_filters": false, "type": "pin" }, "record_match": { "$and": [ { "brand": { "in": [ "nike", "adidas" ] } }, { "lbx:price": { "gte": 50, "lte": 200 } }, { "$or": [ { "condition": { "eq": "new" } }, { "warranty_months": { "gte": 12 } } ] }, { "$not": { "material": { "eq": "leather" } } }, { "image": { "exists": true } } ] } } ], "status": "draft", "timezone": "UTC"}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
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.