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.
| Method | Path | Description |
|---|---|---|
GET | /rules/{context}/global | Get a context's global rules |
PUT | /rules/{context}/global | Replace a context's global rules |
Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise.
Fields
| Field | Type | Default | Description |
|---|---|---|---|
filters | string[] | [] | Up to 10 filter expressions, ANDed. |
scoreModifiers | object | {} | Boosts and buries as {field: weight}. |
recency | object or null | null | A recency boost. |
reinforcementLearning | boolean | true | Whether shopper-activity boosts apply in this context. |
inheritFromGlobalSearch | boolean | see below | Recommendation contexts only. See Inheriting search's global rules. |
context | string | Read-only. | |
revision | string | Read-only. See Revisions. | |
updatedAt | string | Read-only. When the rules were last saved. |
Get global rules
Endpoint: GET /rules/{context}/global
- cURL
- JavaScript
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/global \
-H "Authorization: Bearer {api_key}"
const response = await fetch(
"https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/global",
{ headers: { Authorization: "Bearer {api_key}" } },
);
const globalRules = await response.json();
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
- JavaScript
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 }
}'
await fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/global", {
method: "PUT",
headers: {
Authorization: "Bearer {api_key}",
"Content-Type": "application/json",
},
body: JSON.stringify({
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, orinheritFromGlobalSearch: trueinsearchorcollection.409 merchandising_not_configured: merchandising isn't set up on the index.412 revision_mismatch:If-Matchdidn'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:
inheritFromGlobalSearch | Filters and score modifiers served |
|---|---|
true | The context's own lists plus search's global ones, combined as a trigger's rules combine with global rules. |
false | The 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
PUTthat omits the field sets it tofalse, so a full replacement means what its body says. Send"inheritFromGlobalSearch": trueto keep inheriting. recencyandreinforcementLearningare never inherited.- In
searchandcollectionthe field is alwaysfalse.
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.