01 Aug 2018

Query Rules REST API

Overview

This is the technical reference guide for our Query Rules REST API. Query Rules allows managing the set of rules for any given index. For a general overview, please see our Query Rules guide.

As their name implies, Query Rules apply at query time. Therefore, some search parameters control how rules are applied.

The Query Rules REST API follows the same conventions as our Search REST API. Please refer to the latter regarding request/response format, authentication and error handling.

Many of the rule endpoints manipulate rule objects, which are described in detail in the Rule format.

Rules Management API

Quick Reference

Verb Path Method

PUT

/1/indexes/{indexName}/rules/{objectID}

Save rule

POST

/1/indexes/{indexName}/rules/batch

Batch rules

DELETE

/1/indexes/{indexName}/rules/{objectID}

Delete rule

POST

/1/indexes/{indexName}/rules/clear

Clear rules

GET

/1/indexes/{indexName}/rules/{objectID}

Get rule

POST

/1/indexes/{indexName}/rules/search

Search rules

Save rule

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

Description:
Create or update the rule with the specified objectID.

Parameters:

indexName
type: string
Required

Index name

objectID
type: string
Required

objectID of the rule to delete

forwardToReplicas
type: boolean
Optional
default: `false`

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example:

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}" \
     --data-binary '{
        "objectID": "a-rule-id",
        "condition": {
          "pattern": "apple",
          "anchoring": "contains"
        },
        "consequence": {
          "params": {
            "filters": "brand:apple"
          }
        }
     }'

Batch rules

Path: /1/indexes/{indexName}/rules/batch
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:
Create or update a batch of rules.

Each rule will be created or updated, depending on whether a rule with the same objectID already exists. You may also specify true for clearExistingRules, in which case the batch will atomically replace all the existing rules.

Parameters:

indexName
type: string
Required

Index name

forwardToReplicas
type: boolean
Optional
default: `false`

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

clearExistingRules
type: boolean
Optional
default: `false`

When true, existing rules are cleared before adding this batch. When false, existing rules are kept.

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/test_rest/rules/batch" \
    --data-binary '[
        {
         "objectID": "a-rule-id",
         "condition": {
           "pattern": "smartphone",
           "anchoring": "contains"
         },
         "consequence": {
           "params": {
             "filters": "category:smartphone"
           }
         }
       },
       {
          "objectID": "a-second-rule-id",
          "condition": {
            "pattern": "apple",
            "anchoring": "contains"
          },
          "consequence": {
            "params": {
              "filters": "brand:apple"
            }
          }
       }
    ]'

Delete rule

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: DELETE
Required API Key: any key with the editSettings ACL

Description:
Delete the rule with the specified objectID.

Parameters:

indexName
type: string
Required

Index name

objectID
type: string
Required

objectID of the rule to delete

forwardToReplicas
type: boolean
Optional
default: `false`

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example:

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Clear rules

Path: /1/indexes/{indexName}/rules/clear
HTTP Verb: POST
Required API Key: any key with the editSettings ACL

Description:
Delete all rules in the index.

Parameters:

indexName
type: string
Required

Index name

forwardToReplicas
type: boolean
Optional
default: `false`

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/clear"

Get rule

Path: /1/indexes/{indexName}/rules/{objectID}
HTTP Verb: GET
Required API Key: any key with the settings ACL

Description:
Retrieve the rule with the specified objectID.

Parameters:

indexName
type: string
Required

Index name

objectID
type: string
Required

objectID of the rule to delete

Example:

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Search rules

Path: /1/indexes/{indexName}/rules/search
HTTP Verb: POST
Required API Key: any key with the settings ACL

Description:
Search for rules.

Parameters:

indexName
type: string
Required

Index name

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/search" \
    --data-binary '{"query": "something"}'
© Algolia - Privacy Policy