Create or replace a rule

If a rule with the specified object ID doesn’t exist, it’s created. Otherwise, the existing rule is replaced.

To create or update more than one rule, use the batch operation.

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

curl

cURL

curl --request PUT \
  --url 'https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/rules/lorem?forwardToReplicas=true' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '
{
  "objectID": "lorem",
  "conditions": [
    {
      "pattern": "{facet:genre}",
      "anchoring": "is",
      "alternatives": false,
      "context": "mobile",
      "filters": "genre:comedy"
    }
  ],
  "consequence": {
    "params": {
      "similarQuery": "comedy drama crime Macy Buscemi",
      "filters": "(category:Book OR category:Ebook) AND _tags:published",
      "facetFilters": [
        [
          "category:Book",
          "category:-Movie"
        ],
        "author:John Doe"
      ],
      "optionalFilters": [
        "category:Book",
        "author:John Doe"
      ],
      "numericFilters": [
        [
          "inStock = 1",
          "deliveryDate < 1441755506"
        ],
        "price < 1000"
      ],
      "tagFilters": [
        [
          "Book",
          "Movie"
        ],
        "SciFi"
      ],
      "sumOrFiltersScores": false,
      "restrictSearchableAttributes": [
        "title",
        "author"
      ],
      "facets": [
        "*"
      ],
      "facetingAfterDistinct": false,
      "page": 0,
      "offset": 42,
      "length": 0,
      "aroundLatLng": "40.71,-74.01",
      "aroundLatLngViaIP": false,
      "aroundRadius": 1,
      "aroundPrecision": 10,
      "minimumAroundRadius": 1,
      "insideBoundingBox": "lorem",
      "insidePolygon": [
        [
          47.3165,
          4.9665,
          47.3424,
          5.0201,
          47.32,
          4.9
        ],
        [
          40.9234,
          2.1185,
          38.643,
          1.9916,
          39.2587,
          2.0104
        ]
      ],
      "naturalLanguages": [],
      "ruleContexts": [
        "mobile"
      ],
      "personalizationImpact": 100,
      "userToken": "test-user-123",
      "getRankingInfo": false,
      "synonyms": true,
      "clickAnalytics": false,
      "analytics": true,
      "analyticsTags": [],
      "percentileComputation": true,
      "enableABTest": true,
      "attributesToRetrieve": [
        "author",
        "title",
        "content"
      ],
      "ranking": [
        "typo",
        "geo",
        "words",
        "filters",
        "proximity",
        "attribute",
        "exact",
        "custom"
      ],
      "relevancyStrictness": 90,
      "attributesToHighlight": [
        "author",
        "title",
        "conten",
        "content"
      ],
      "attributesToSnippet": [
        "content:80",
        "description"
      ],
      "highlightPreTag": "<em>",
      "highlightPostTag": "</em>",
      "snippetEllipsisText": "…",
      "restrictHighlightAndSnippetArrays": false,
      "hitsPerPage": 20,
      "minWordSizefor1Typo": 4,
      "minWordSizefor2Typos": 8,
      "typoTolerance": true,
      "allowTyposOnNumericTokens": true,
      "disableTypoToleranceOnAttributes": [
        "sku"
      ],
      "ignorePlurals": [
        "ca",
        "es"
      ],
      "removeStopWords": [
        "ca",
        "es"
      ],
      "queryLanguages": [
        "es"
      ],
      "decompoundQuery": true,
      "enableRules": true,
      "enablePersonalization": false,
      "queryType": "prefixLast",
      "removeWordsIfNoResults": "firstWords",
      "mode": "keywordSearch",
      "semanticSearch": {
        "eventSources": [
          "lorem"
        ]
      },
      "advancedSyntax": false,
      "optionalWords": "lorem",
      "disableExactOnAttributes": [
        "description"
      ],
      "exactOnSingleWordQuery": "attribute",
      "alternativesAsExact": [
        "ignorePlurals",
        "singleWordSynonym"
      ],
      "advancedSyntaxFeatures": [
        "exactPhrase",
        "excludeWords"
      ],
      "distinct": 1,
      "replaceSynonymsInHighlight": false,
      "minProximity": 1,
      "responseFields": [
        "*"
      ],
      "maxValuesPerFacet": 100,
      "sortFacetValuesBy": "count",
      "attributeCriteriaComputedByMinProximity": false,
      "renderingContent": {
        "facetOrdering": {
          "facets": {
            "order": [
              "lorem"
            ]
          },
          "values": {
            "property1": {
              "order": [
                "lorem"
              ],
              "sortRemainingBy": "count",
              "hide": [
                "lorem"
              ]
            },
            "property2": {
              "order": [
                "lorem"
              ],
              "sortRemainingBy": "count",
              "hide": [
                "lorem"
              ]
            }
          }
        },
        "redirect": {
          "url": "lorem"
        },
        "widgets": {
          "banners": [
            {
              "image": {
                "urls": [
                  {
                    "url": "lorem"
                  }
                ],
                "title": "lorem"
              },
              "link": {
                "url": "lorem"
              }
            }
          ]
        }
      },
      "enableReRanking": true,
      "reRankingApplyFilter": [
        []
      ],
      "query": {
        "remove": [
          "lorem"
        ],
        "edits": [
          {
            "type": "remove",
            "delete": "lorem",
            "insert": "lorem"
          }
        ]
      },
      "automaticFacetFilters": [
        {
          "facet": "lorem",
          "score": 1,
          "disjunctive": false
        }
      ],
      "automaticOptionalFacetFilters": [
        {
          "facet": "lorem",
          "score": 1,
          "disjunctive": false
        }
      ]
    },
    "promote": [
      {
        "objectIDs": [
          "test-record-123"
        ],
        "position": 0
      }
    ],
    "filterPromotes": false,
    "hide": [
      {
        "objectID": "test-record-123"
      }
    ],
    "redirect": {
      "indexName": "lorem"
    },
    "userData": {
      "settingID": "f2a7b51e3503acc6a39b3784ffb84300",
      "pluginVersion": "1.6.0"
    }
  },
  "description": "Display a promotional banner",
  "enabled": true,
  "validity": [
    {
      "from": 42,
      "until": 42
    }
  ],
  "tags": [
    "lorem"
  ],
  "scope": "lorem"
}
'

200

{
  "taskID": 1514562690001,
  "updatedAt": "2023-07-04T12:49:15Z"
}

Required ACL: editSettings

Authorizations

x-algolia-application-id · string · header · required

Your Algolia application ID.

x-algolia-api-key · string · header · required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Path Parameters

indexName · string · required

Name of the index on which to perform the operation.

Example:

"ALGOLIA_INDEX_NAME"

objectID · string · required

Unique identifier of a rule object.

Query Parameters

forwardToReplicas · boolean

Whether changes are applied to replica indices.

Body

application/json

Rule object.

objectID · string · required

Unique identifier of a rule object.

consequence · object · required

Effect of the rule.

For more information, see Consequences.

Show child attributes

conditions · object[]

Conditions that trigger a rule.

Some consequences require specific conditions or don't require any condition. For more information, see Conditions.

Maximum array length: 25

Show child attributes

description · string

Description of the rule's purpose to help you distinguish between different rules.

Example:

"Display a promotional banner"

enabled · boolean · default: true

Whether the rule is active.

validity · object[]

Time periods when the rule is active.

Show child attributes

tags · string[]

scope · string

Response

200

application/json

OK

Response, taskID, and update timestamp.

taskID · integer<int64> · required

Unique identifier of a task.

A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the task operation and this task ID.

Example:

1514562690001

updatedAt · string · required

Date and time when the object was updated, in RFC 3339 format.

Example:

"2023-07-04T12:49:15Z"