Skip to main content

Add Rules

curl -X POST -H "Content-Type: application/json" \
  -d '{
        "query": "leashes",
        "slot_rules": [
            {
                "position": 1,
                "item_id": "very_cool_dog_leash_id",
                "fuzzy_match": true,
                "labels": {
                  "is_sponsored": true
                }
            }
        ]
    }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/refined_queries?key=[your API key]&section=[section]"
info

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if some or all items already exist.

HTTP Request​

POST https://ac.cnstrc.com/v1/refined_queries?key=[your API key]&section=[section]

URL Parameters​

ParameterRequired?Description
sectionYesThe index section you'd like to retrieve results from (typically Products).

JSON Specifications​

Example JSON
{
  "query": "dog food",
  "slot_rules": [
    {
      "rule": {
        "item_id": "fiddos_food_item",
        "position": 1,
        "fuzzy_match": true,
        "labels": {
          "is_sponsored": true
        }
      },
      "active": true,
      "start_time": "2018-06-28 01:34:08",
      "end_time": "2018-06-30 01:34:08"
    }
  ],
  "whitelist_rule": {
    "rule": {
      "filters": { "brand": ["fiddos food"] }
    },
    "end_time": "2018-06-28 01:34:08"
  },
  "blacklist_rules": [
    {
      "rule": {
        "filters": { "type": ["toys"] }
      },
      "start_time": "2018-06-28 01:34:08",
      "end_time": "2018-06-30 01:34:08"
    },
    {
      "rule": {
        "item_ids": ["toy_item_1", "toy_item_2"]
      },
      "start_time": "2018-06-28 01:34:08"
    }
  ],
  "boost_rules": [
    {
      "rule": {
        "filters": { "color": ["red"] },
        "boost": 0.5
      }
    },
    {
      "rule": {
        "item_ids": ["food_item_1", "food_item_2"]
      },
      "end_time": "2018-06-30 01:34:08"
    }
  ],
  "content_rules": [
    {
      "rule": {
        "data": {
          "header": "<h1>Special offer on eyelash care products in our beauty salons</h1>",
          "banner_url": "https://example.com/1.png"
        }
      },
      "active": true,
      "start_time": "2020-04-07T13:45:42",
      "end_time": "2020-04-17T13:45:42"
    },
    {
      "rule": {
        "data": {
          "any_key": "any_value"
        }
      },
      "active": true,
      "start_time": "2020-04-07T13:45:42",
      "end_time": "2020-04-17T13:45:42"
    }
  ]
}
info

It is possible to create global search rules (rules that are used in all search requests) by setting the query to *

JSON parameters​

idDescription
queryThe affected query. This can be * if you would like the rule to apply for all queries (i.e: create a global search rule).
slot_rulesWith slot rules, you can add an item to recall and pin it to a specific position. Provide item_id, position for the item(s) and fuzzy_match to determine if the rule should be applied only when there's an exact query match. labels can be used to add other miscellaneous properties for the item. It can be an empty object, or can have these properties.
boost_rulesBoost or bury the score (and in turn, ranking) of matching items.
whitelist_ruleRestrict recall to only the matching items.
blacklist_rulesRemove matching items from recall.
content_rulesAttach specified JSON content to the search query response. *

Rule Definitions​

ParameterRequired?Description
ruleYesRules can accept an object of the various rule specs as show in the above JSON example. Note that blacklist & boost rules can accept either a filters object, or an item_ids array. The data attribute of content rules can contain any custom data, the only limitation is the total size of the object - it can't exceed 200kB
activeNoYour searchandizing rules can be defined but set to inactive if you wish by setting the active field to false.
start_timeNoStart time when the searchandizing rule should be enabled.
end_timeNoEnd time when the searchandizing rule should be disabled.

List of properties that can be added to labels

  • is_sponsored specifies if the slotted item is advertised or promoted.