Search for rules

Searches for Recommend rules.

Use an empty query to list all rules for this recommendation scenario.

POST /1/indexes/{indexName}/{model}/recommend/rules/search

curl

cURL

curl --request POST \
  --url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/related-products/recommend/rules/search \
  --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 '{"query":"","context":"mobile","page":0,"hitsPerPage":20,"enabled":true,"filters":"objectID:rr-123456","facets":["*"],"maxValuesPerFacet":1}'

200

{
  "hits": [
    {
      "_metadata": {
        "lastUpdate": "2023-07-04T12:49:15Z"
      },
      "objectID": "<string>",
      "condition": {
        "filters": "(category:Book OR category:Ebook) AND _tags:published",
        "context": "mobile"
      },
      "consequence": {
        "hide": [
          {
            "objectID": "test-record-123"
          }
        ],
        "promote": [
          {
            "objectID": "test-record-123",
            "position": 1
          }
        ],
        "params": {
          "automaticFacetFilters": [
            {
              "facet": "<string>",
              "negative": true
            }
          ],
          "filters": "(category:Book OR category:Ebook) AND _tags:published",
          "optionalFilters": [
            "category:books<score=1>",
            "category:-movies<score=1>"
          ]
        }
      },
      "description": "Boost on-sale items",
      "enabled": true,
      "validity": [
        {
          "from": 123,
          "until": 123
        }
      ]
    }
  ],
  "nbHits": 20,
  "page": 0,
  "nbPages": 1
}

Required ACL: settings

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"

model · enum<string> · required

Recommend model.

Available options: related-products, bought-together, trending-facets, trending-items

Body

application/json

Recommend rules parameters.

query · string · default: ""

Search query.

context · string

Only search for rules with matching context.

Example:

"mobile"

page · integer

Requested page of the API response.

Algolia uses page and hitsPerPage to control how search results are displayed (paginated).

• hitsPerPage: sets the number of search results (hits) displayed per page.
• page: specifies the page number of the search results you want to retrieve. Page numbering starts at 0, so the first page is page=0, the second is page=1, and so on.

For example, to display 10 results per page starting from the third page, set hitsPerPage to 10 and page to 2.

Required range: x >= 0

hitsPerPage · integer · default: 20

Maximum number of hits per page.

Algolia uses page and hitsPerPage to control how search results are displayed (paginated).

• hitsPerPage: sets the number of search results (hits) displayed per page.
• page: specifies the page number of the search results you want to retrieve. Page numbering starts at 0, so the first page is page=0, the second is page=1, and so on.

For example, to display 10 results per page starting from the third page, set hitsPerPage to 10 and page to 2.

Required range: 1 <= x <= 1000

enabled · boolean

Whether to only show rules where the value of their enabled property matches this parameter. If absent, show all rules, regardless of their enabled property.

filters · string

Filter expression. This only searches for rules matching the filter expression.

Example:

"objectID:rr-123456"

facets · string[]

Include facets and facet values in the response. Use ['*'] to include all facets.

Facet name for rule objects or * as wildcard character.

Example:

["*"]

maxValuesPerFacet · integer

Maximum number of values to return for each facet.

Required range: 1 <= x <= 1000

Response

200

application/json

OK

hits · object[] · required

Recommend rules that match the search criteria.

Show child attributes

hits. _metadata · ruleMetadata · object

Rule metadata.

Show child attributes

hits._metadata. lastUpdate · string

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

Example:

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

hits. objectID · string

Unique identifier of a rule object.

hits. condition · object

Condition that triggers the rule. If not specified, the rule is triggered for all recommendations.

Show child attributes

hits.condition. filters · string

Filter expression to only include items that match the filter criteria in the response.

You can use these filter expressions:

• Numeric filters. <facet> <op> <number>, where <op> is one of <, <=, =, !=, >, >=.
• Ranges. <facet>:<lower> TO <upper> where <lower> and <upper> are the lower and upper limits of the range (inclusive).
• Facet filters. <facet>:<value> where <facet> is a facet attribute (case-sensitive) and <value> a facet value.
• Tag filters. _tags:<value> or just <value> (case-sensitive).
• Boolean filters. <facet>: true | false.

You can combine filters with AND, OR, and NOT operators with the following restrictions:

• You can only combine filters of the same type with OR. Not supported: facet:value OR num > 3.
• You can't use NOT with combinations of filters. Not supported: NOT(facet:value OR facet:value)
• You can't combine conjunctions (AND) with OR. Not supported: facet:value OR (facet:value AND facet:value)

Use quotes around your filters, if the facet attribute name or facet value has spaces, keywords (OR, AND, NOT), or quotes. If a facet attribute is an array, the filter matches if it matches at least one element of the array.

For more information, see Filters.

Example:

"(category:Book OR category:Ebook) AND _tags:published"

hits.condition. context · string

An additional restriction that only triggers the rule, when the search has the same value as ruleContexts parameter. For example, if context: mobile, the rule is only triggered when the search request has a matching ruleContexts: mobile. A rule context must only contain alphanumeric characters.

Example:

"mobile"

hits. consequence · object

Effect of the rule.

Show child attributes

hits.consequence. hide · object[]

Exclude items from recommendations.

Minimum array length: 1

Show child attributes

hits.consequence.hide. objectID · string

Unique record identifier.

Example:

"test-record-123"

hits.consequence. promote · object[]

Place items at specific positions in the list of recommendations.

Minimum array length: 1

Show child attributes

hits.consequence.promote. objectID · string

Unique record identifier.

Example:

"test-record-123"

hits.consequence.promote. position · integer

Index in the list of recommendations where to place this item.

Required range: x >= 0

hits.consequence. params · object

Filter or boost recommendations matching a facet filter.

Show child attributes

hits.consequence.params. automaticFacetFilters · object[]

Filter recommendations that match or don't match the same facet:facet_value combination as the viewed item.

Show child attributes

hits.consequence.params.automaticFacetFilters. facet · string

Facet attribute.

hits.consequence.params.automaticFacetFilters. negative · boolean

Whether the filter is negative. If true, recommendations must not have the same value for the facet attribute. If false, recommendations must have the same value for the facet attribute.

hits.consequence.params. filters · string

Filter expression to only include items that match the filter criteria in the response.

You can use these filter expressions:

• Numeric filters. <facet> <op> <number>, where <op> is one of <, <=, =, !=, >, >=.
• Ranges. <facet>:<lower> TO <upper> where <lower> and <upper> are the lower and upper limits of the range (inclusive).
• Facet filters. <facet>:<value> where <facet> is a facet attribute (case-sensitive) and <value> a facet value.
• Tag filters. _tags:<value> or just <value> (case-sensitive).
• Boolean filters. <facet>: true | false.

You can combine filters with AND, OR, and NOT operators with the following restrictions:

• You can only combine filters of the same type with OR. Not supported: facet:value OR num > 3.
• You can't use NOT with combinations of filters. Not supported: NOT(facet:value OR facet:value)
• You can't combine conjunctions (AND) with OR. Not supported: facet:value OR (facet:value AND facet:value)

Use quotes around your filters, if the facet attribute name or facet value has spaces, keywords (OR, AND, NOT), or quotes. If a facet attribute is an array, the filter matches if it matches at least one element of the array.

For more information, see Filters.

Example:

"(category:Book OR category:Ebook) AND _tags:published"

hits.consequence.params. optionalFilters · string[]

Filters to promote or demote records in the search results.

Optional filters work like facet filters, but they don't exclude records from the search results. Records that match the optional filter rank before records that don't match. Matches with higher weights (<score=N>) rank before matches with lower weights. If you're using a negative filter facet:-value, matching records rank after records that don't match.

Example:

[
  "category:books<score=1>",
  "category:-movies<score=1>"
]

hits. description · string

Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.

Example:

"Boost on-sale items"

hits. enabled · boolean · default: true

Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.

hits. validity · object[]

Time periods when the rule is active.

Show child attributes

hits.validity. from · integer<int64>

When the rule should start to be active, in Unix epoch time.

hits.validity. until · integer<int64>

When the rule should stop to be active, in Unix epoch time.

nbHits · integer · required

Number of results (hits).

Example:

20

page · integer · default: 0 · required

Page of search results to retrieve.

Required range: x >= 0

nbPages · integer · required

Number of pages of results.

Example:

1