Skip to main content

Global Rules API

Overview​

Global rules are the defaults for a context: filters, boosts and recency that apply to every search query, collection or recommendation in it. A trigger's own rules are added on top, unless the trigger opts out (see Inheriting global rules).

Each context has exactly one global rule set. It always exists: before anything is saved, a read returns the defaults.

MethodPathDescription
GET/rules/{context}/globalGet a context's global rules
PUT/rules/{context}/globalReplace a context's global rules

Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise.

Fields​

FieldTypeDefaultDescription
filtersstring[][]Up to 10 filter expressions, ANDed.
scoreModifiersobject{}Boosts and buries as {field: weight}.
recencyobject or nullnullA recency boost.
reinforcementLearningbooleantrueWhether shopper-activity boosts apply in this context.
inheritFromGlobalSearchbooleansee belowRecommendation contexts only. See Inheriting search's global rules.
contextstringRead-only.
revisionstringRead-only. See Revisions.
updatedAtstringRead-only. When the rules were last saved.

Get global rules​

Endpoint: GET /rules/{context}/global

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

Response​

{
"context": "search",
"filters": ["NOT category:(Gift Cards)", "in_stock:true"],
"scoreModifiers": { "margin": 0.2, "_merch_brand.nike": 0.5 },
"recency": { "before": 60, "after": 14, "weight": 0.8, "sliderValue": 0.8 },
"reinforcementLearning": true,
"inheritFromGlobalSearch": false,
"revision": "9c41e07b2d5a4f3e8a1b6c7d0e2f4a5b",
"updatedAt": "2026-10-30T03:15:42.123Z"
}

Replace global rules​

Endpoint: PUT /rules/{context}/global

The body replaces the whole rule set. Omitted fields take their defaults: filters [], scoreModifiers {}, recency null, reinforcementLearning true and inheritFromGlobalSearch false. Global rules always exist, so the write takes If-Match only.

curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/global \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"filters": ["NOT category:(Gift Cards)"],
"scoreModifiers": { "margin": 0.2 },
"recency": { "before": 60, "after": 14, "weight": 0.8 }
}'

The response is the stored rule set, with its new revision in the body and the ETag header.

Errors specific to this operation:

  • 400 validation_error: an invalid filter or score modifier, more than 10 filters, a negative recency weight, or inheritFromGlobalSearch: true in search or collection.
  • 409 merchandising_not_configured: merchandising isn't set up on the index.
  • 412 revision_mismatch: If-Match didn't match.

Global rules have no pins or exclusions, so the per-index limits don't apply and there is no 422.

Inheriting search's global rules​

The recommendation contexts (similar, complementary, complete_the_look) can also serve the search context's global filters and score modifiers. inheritFromGlobalSearch switches that on or off for both:

inheritFromGlobalSearchFilters and score modifiers served
trueThe context's own lists plus search's global ones, combined as a trigger's rules combine with global rules.
falseThe context's own lists only. An empty list means none.
  • A recommendation context with nothing saved reads back true, which is how it serves.
  • A PUT that omits the field sets it to false, so a full replacement means what its body says. Send "inheritFromGlobalSearch": true to keep inheriting.
  • recency and reinforcementLearning are never inherited.
  • In search and collection the field is always false.
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/similar/global \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"inheritFromGlobalSearch": false,
"filters": ["in_stock:true"]
}'

This makes Similar recommendations use only in_stock:true, without the search context's boosts.