Authenticate with an API key that has the editSettings ACL on the target index.
Create a rule by sending a PUT request to /1/indexes/{indexName}/rules/{objectID}; the request body includes a conditions array (each condition has a pattern and an anchoring field such as 'is', 'startsWith', or 'contains'), and a consequences object.
In consequences, use promote (with objectID and position) to pin items, hide to suppress objectIDs, filterPromotes to restrict boost scope, and params.filters or params.query to inject extra query parameters when the rule fires.
Optionally set validity as an array of start/end Unix timestamps to create time-limited rules for promotions or seasonal campaigns.
Test the rule by issuing a search with the matching query and getRankingInfo:true; confirm the rule is reflected in the appliedRules field of the response.
Known gotchas
A rule with no conditions is always applied (conditionless rule); review carefully before deploying to production to avoid unintended global effects.
Rules use a single index scope; replicas do not automatically inherit rules from the primary index unless you push rules to each index explicitly.
The 2025 Rules Analytics feature lets you identify stale or low-impact rules — audit regularly to keep rule sets lean.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp