Create a rule

POST /v25-10-beta/agentic-logic/rules

Creates a rule in the draft state. The response is { rule }.

• name (string, required) — Merchant-facing rule name.
• description (string, required, 1–1024 characters) — Plain-language summary of what the rule recommends, in what order, and for which shoppers.
• managedBy (string, required) — builder for a template-configured rule, or code for a rule whose source you author through the draft endpoint. Fixed after creation.
• settings (object, optional) — Recommendation settings: maxItems (1–10), excludeOutOfStock, excludeItemsInCart, and onEmpty (hide or smart-recs), all required when the object is sent. Omit it to take the defaults: 3 items, both exclusions on, hide.

A builder rule also takes:

• templateId (string, required) — Template to configure.
• templateParams (object, optional) — Validated against the template's params schema.
• templateVersion (number, optional) — Template version the params were written against.

Builder rules don't take targetSurfaces; their template sets the surfaces.

A code rule also takes:

• targetSurfaces (string array, required) — The surfaces (onsite, checkout, post-purchase) whose placements the rule may be assigned to. Non-empty, with no repeats, and fixed after creation.
• authoringSessionId (string, optional) — The AI chat session authoring the rule.

A code-rule body is strict: unknown fields are rejected.

Creating a builder rule starts its first publish. A code rule needs a saved draft before it can publish (see Save a code rule's draft). A rule serves nothing until it has an active version and is assigned to a placement.

Use the intelligems-access-token header. The token selects the organization; do not send orgId. The organization must have Agentic Logic enabled.

Rate Limit: 50 requests per 30s window, refilling 25 tokens every 30s.