Skip to main content

Trigger Rules API

Overview​

A trigger rule set holds the rules for one trigger in a context: a search query, a collection id, or a seed product for a recommendation shelf. It can pin products to positions, exclude products, boost or bury by field, add filters and a recency boost, and carry scheduled overrides that replace the rules during a time window.

MethodPathDescription
GET/rules/{context}/triggersList the triggers that have rules
GET/rules/{context}/triggers/{trigger}Get one trigger's rules
PUT/rules/{context}/triggers/{trigger}Create or replace one trigger's rules
DELETE/rules/{context}/triggers/{trigger}Delete one trigger's rules
GET/rules/{context}/triggers/{trigger}/schedule-historyList the trigger's ended scheduled overrides

Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise. Encode {trigger} as one path segment (see Triggers in the path).

Rule set fields​

FieldTypeDefaultDescription
pinsobject[][]Products fixed at a position. See Pins and exclusions.
excludesobject[][]Products removed from results.
scoreModifiersobject{}Boosts and buries as {field: weight}. See Score modifiers.
filtersstring[][]Up to 10 filter expressions, ANDed. See Filters.
recencyobject or nullnullA recency boost. See Recency.
inheritGlobalFiltersbooleantrueAlso apply the context's global filters.
inheritGlobalScoreModifiersbooleantrueAlso apply the context's global score modifiers and global recency.
applyOutOfStockFilterbooleantrueApply the index's out-of-stock filter.
reinforcementLearningstringglobalShopper-activity boosts: global follows the context's global setting, enable and disable override it.
overrideRelevancebooleanfalseAlso apply boosts to the semantic score, so they can outweigh relevance. Ignored in collection and complementary, which rank lexically, and stored as false there.
scheduledOverridesobject[][]Alternative rule sets for a time window. See Scheduled overrides.
context, triggerstringRead-only. trigger is the canonical form.
requestedTriggerstringRead-only. Set when a read named a synonym child.
revision, updatedAtstringRead-only.

On a write, omitted fields take their defaults.

Pins and exclusions​

{
"pins": [
{ "position": 1, "documentId": "sku-48213" },
{ "position": 2, "documentId": "sku-10377" }
],
"excludes": [{ "documentId": "sku-99120" }]
}
  • position is 1-based, unique within the rule set, and at most the index's highest pin position (120 by default).
  • documentId is the document's _id.
  • A rule set names each document once across pins and excludes. Pinning a document twice, excluding it twice, or pinning and excluding it is 400 validation_error, naming the document. Each scheduled override is checked on its own, so an override may pin a document the baseline excludes.

Score modifiers​

Score modifiers boost or bury results as a map of {field: weight}. Each adds weight × the field's value to a result's score; a negative weight buries.

{
"scoreModifiers": {
"rating": 0.3,
"_merch_brand.nike": 1.5,
"_merch_tags.clearance": -2
}
}
  • A numeric or boolean document field, such as margin, rating or instock, is the key itself.
  • A value of a ranking field is _merch_<field>.<value>. Register ranking fields first with POST /config/merchandise/fields. The field and value are normalised as the index stores them (lower case, other characters than letters, digits, _ and - become _), so _merch_brand.Calvin Klein is stored and returned as _merch_brand.calvin_klein. Two keys that normalise to the same thing are 400 validation_error.
  • A bare ranking field such as _merch_brand, with no value, matches nothing and is 400 validation_error.
  • _id can't be boosted (400 validation_error).
  • A weight is 0 or a magnitude between 1e-100 and 1e15.
  • Map order carries no meaning.

Writing back a rule set you read keeps boosts set up in the console as they were; only a changed weight changes the stored boost.

Filters​

Each filter is one Marqo filter expression, and the filters in the list are ANDed:

{
"filters": [
"NOT category:(Gift Cards)",
"price:[10 TO 500]",
"brand:(Acme) OR brand:(Globex)",
"in_stock:true"
]
}
  • At most 10 filters, each at most 1,024 characters. Leading and trailing whitespace is removed.
  • Escape \, (, ), :, [ and ] inside a value with a backslash: brand:(Acme \(Outlet\)). Nothing is escaped for you.
  • Invalid syntax is 400 validation_error with the column of the first problem: unbalanced parentheses, a dangling AND, an empty value (brand:()), lower-case and/or/not, &&, ||, !, a keyword glued to ( (NOT(a:b)), or a tab or newline between terms.
  • IN works only on _id and the index's collapse fields (usually parentProductId). Write color:(Black) OR color:(Blue) rather than color IN (Black, Blue).
  • CONTAINS works only on fields holding a single text value (title CONTAINS dress), not on lists such as tags, numbers, booleans or _id. Write tags:(Sale) to match a whole value.
  • A filter built in the console is returned as its expression. Writing it back unchanged keeps it as the console's filter, at any length; a filter you add or edit shows in the console as a custom expression.

Recency​

Recency boosts documents by how recent the index's recency field is. Set the recency field in the console first; until it is set, recency rules have no effect.

{ "recency": { "before": 30, "after": 7, "weight": 1.2 } }
FieldDescription
beforeDays before now over which the boost grows.
afterDays of full boost.
weightStrength of the boost, 0 or more. 0 turns recency off and, on a trigger, also blocks the global recency.
sliderValueOptional console display hint. Defaults to weight.

Send "recency": null (or omit it) for no recency boost of the trigger's own.

Inheriting global rules​

A trigger's rules are added to the context's global rules:

FlagWhen true (default)When false
inheritGlobalFiltersGlobal filters and the trigger's filters both apply.Only the trigger's filters apply.
inheritGlobalScoreModifiersGlobal score modifiers and recency apply, plus the trigger's.Only the trigger's score modifiers and recency apply.

reinforcementLearning: global follows the context's global setting whatever inheritGlobalScoreModifiers says.

List triggers​

Endpoint: GET /rules/{context}/triggers

Returns a summary of each stored rule set, ordered by trigger. Read a trigger's rules with Get rules. Paginated with limit and cursor (see Pagination).

curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/collection/triggers?limit=50" \
-H "Authorization: Bearer {api_key}"
{
"items": [
{
"trigger": "running shoes",
"revision": "9c41e07b2d5a4f3e8a1b6c7d0e2f4a5b",
"updatedAt": "2026-10-30T03:15:42.123Z",
"updatedBy": "merchandiser@example.com"
}
],
"nextCursor": "eyJrIjoicnVubmluZyBzaG9lcyJ9"
}

updatedBy is the console user's email, api_key:<id> for a change made with an API key (<id> is stable per key and reveals nothing about it), or null when unknown. Compare each revision with the one you last read to find the triggers that changed without fetching them all.

Get rules​

Endpoint: GET /rules/{context}/triggers/{trigger}

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}"

Response​

{
"context": "search",
"trigger": "running shoes",
"pins": [{ "position": 1, "documentId": "sku-48213" }],
"excludes": [{ "documentId": "sku-99120" }],
"scoreModifiers": { "_merch_brand.nike": 1.5 },
"filters": ["NOT category:(Gift Cards)"],
"recency": null,
"inheritGlobalFilters": true,
"inheritGlobalScoreModifiers": true,
"applyOutOfStockFilter": true,
"reinforcementLearning": "global",
"overrideRelevance": false,
"scheduledOverrides": [],
"revision": "9c41e07b2d5a4f3e8a1b6c7d0e2f4a5b",
"updatedAt": "2026-10-30T03:15:42.123Z"
}

A trigger with no rules returns 404 rule_set_not_found.

Create or replace rules​

Endpoint: PUT /rules/{context}/triggers/{trigger}

Replaces the trigger's whole rule set, scheduled overrides included, or creates it. Send If-Match with the revision you read to avoid overwriting a concurrent edit, or If-None-Match: * to create only if no rule set exists.

curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/collection/triggers/summer-sale \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"pins": [
{ "position": 1, "documentId": "sku-48213" },
{ "position": 2, "documentId": "sku-10377" }
],
"excludes": [{ "documentId": "sku-99120" }],
"scoreModifiers": { "_merch_brand.acme": 2, "margin": 0.4 },
"filters": ["price:[* TO 200]"]
}'

The response is the stored rule set (200) with its new revision.

Editing one rule​

To add a pin without losing the rest, read the rule set, change it and write the whole body back, with its revision as If-Match:

const url = `https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/${encodeURIComponent("boots")}`;
const headers = { Authorization: "Bearer {api_key}", "Content-Type": "application/json" };

const current = await fetch(url, { headers });
const rules = await current.json();
rules.pins.push({ position: 3, documentId: "sku-77001" });

const saved = await fetch(url, {
method: "PUT",
headers: { ...headers, "If-Match": current.headers.get("ETag") },
body: JSON.stringify(rules),
});
if (saved.status === 412) {
// Someone else changed the rules since we read them: read again and retry.
}

Empty rule sets​

A rule set is empty when it has no pins, exclusions, filters, score modifiers, recency or scheduled overrides, and every flag is at its default. A PUT that leaves the rule set empty deletes it and returns 204. A rule set that only sets a flag, such as {"reinforcementLearning": "disable"}, is kept.

Errors​

  • 409 trigger_is_synonym_child: in search, the trigger is a synonym child. Write to the parent named in the message instead.
  • 409 profile_rule_sets_exist: the write would empty the rule set while a merchandising profile holds rules for the trigger (see Merchandising profiles).
  • 409 merchandising_not_configured: merchandising isn't set up on the index.
  • 412 revision_mismatch: the precondition failed.
  • 422 limit_*: a limit would be exceeded.
  • 400 resource_too_large: the stored rule set would exceed 400 KB.

Delete rules​

Endpoint: DELETE /rules/{context}/triggers/{trigger}

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}"

Returns 204. The schedule history is kept. Returns 404 rule_set_not_found if the trigger has no rules, including on a retry after a delete that succeeded. Takes an optional If-Match.

Scheduled overrides​

A scheduled override is a complete alternative rule set that replaces the trigger's baseline rules during the half-open window [publishAt, unpublishAt). See Scheduled Rules for how they work in the console.

{
"pins": [{ "position": 1, "documentId": "sku-123" }],
"scheduledOverrides": [
{
"name": "Black Friday",
"publishAt": "2026-11-27T00:00:00-05:00",
"unpublishAt": "2026-12-01T00:00:00-05:00",
"pins": [{ "position": 1, "documentId": "sku-bf-1" }],
"scoreModifiers": { "_merch_tags.black_friday": 3 }
}
]
}

An override takes the rule fields and flags from Rule set fields (pins through overrideRelevance), but not scheduledOverrides or the read-only fields, which are 400 validation_error inside an override. It also takes:

FieldDescription
idStable id, assigned by the server when omitted. Send it back to keep the override's identity across edits.
nameOptional label, up to 100 characters.
publishAtWhen the window opens. Omit for a window that is already open.
unpublishAtWhen the window closes. Omit for a window that never closes.
selectedRead-only. Whether the saved configuration selects this override right now.
  • At least one of publishAt and unpublishAt is required, and unpublishAt must be later than publishAt (400 invalid_schedule_window).
  • Timestamps are RFC 3339 with an explicit offset (Z or ±hh:mm). They are returned in UTC, truncated to milliseconds.
  • Windows may overlap. Among open windows, the one with the latest publishAt wins (a missing publishAt counts as earliest); on a tie, the later entry in the list wins.
  • To edit one override, read the rule set, change that override (keeping its id) and write the whole body back.

Schedule history​

Ended overrides, and overrides that can never be selected again because a later override has started and never ends, move to the schedule history on the next save that changes the rule set. Writing back an unchanged body archives nothing.

  • A save can carry up to 40 overrides, so ended ones can be archived in the same write, but at most 20 may remain after archiving (422 limit_max_scheduled_overrides_per_trigger).
  • Only an override already stored on the rule set is archived. One that matches no stored override, such as a new override sent already ended, is dropped: the save succeeds, and the override is neither stored nor archived.

Endpoint: GET /rules/{context}/triggers/{trigger}/schedule-history

Lists archived overrides, newest endedAt first, paginated with limit and cursor. A page can hold fewer than limit items and still return a nextCursor, because large overrides end a page early.

{
"items": [
{
"override": {
"id": "ovr_7Kq2Lm9X",
"name": "Black Friday",
"publishAt": "2026-11-27T05:00:00.000Z",
"unpublishAt": "2026-12-01T05:00:00.000Z",
"pins": [{ "position": 1, "documentId": "sku-bf-1" }],
"excludes": [],
"scoreModifiers": {},
"filters": [],
"recency": null,
"inheritGlobalFilters": true,
"inheritGlobalScoreModifiers": true,
"applyOutOfStockFilter": true,
"reinforcementLearning": "global",
"overrideRelevance": false
},
"endedAt": "2026-12-01T05:00:00.000Z"
}
],
"nextCursor": null
}

endedAt is when the override stopped serving for good: its unpublishAt, or earlier if a later override that never ends took over.

Synonyms​

In the search context, a query equal to a synonym child is rewritten to its parent before rules apply, so a child has no rules of its own:

  • GET of a child returns the parent's rule set, with trigger set to the parent and requestedTrigger to the child. If the parent has no rules, it is 404 rule_set_not_found, naming the parent.
  • PUT and DELETE of a child fail with 409 trigger_is_synonym_child, naming the parent.

Merchandising profiles​

The API reads and writes each trigger's default rule set only. Rule sets and schedules that the console writes for a merchandising profile keep serving, are not listed, and are managed in the console.

Deleting a default rule set, or a PUT that would empty it, fails with 409 profile_rule_sets_exist while a profile holds a rule set or scheduled rules for the trigger. The message names each profile and what it holds. Remove them in the console first; a profile's scheduled rules are in its Schedule panel and stay after Revert to Default.