Skip to main content

Redirect Rules

Redirect rules allow customers to alter the destination of users' queries. Imagine a user searches for shopping cart: redirects allow a customer to send this user to the shopping cart URL rather than a search result page for shopping cart products.

The redirect rule endpoint allows customers to define a set of patterns that are checked against search queries; if there is a match, the search endpoint returns a redirect response to the client pointing to the desired target URL (or alternative content identifier in mobile contexts).

Rules are matched in order of specificity, from most specific to least. This allows customers to set one redirect for a broad term, but override this with more specific keywords or phrases.

Redirect objects​

In this section the json objects that are sent to/returned by the API are described.

Redirect rule object​

The redirect rule object describes a complete redirect rule and may have multiple, separate match conditions (matches). For example, dog mattresses and dog beds could be defined to target the same URL.

AttributeTypeRequired?Description
urlstringYesTarget URL returned when a match happens
matchesList[RedirectRuleMatch]YesList of match definitions
start_timestringNoTime at which rule begins to apply (ISO8601 format preferred)
end_timestringNoTime at which rule stops to apply (ISO8601 format preferred)
user_segmentsList[str]NoList of user segments
metadataObjectNoObject with arbitrary metadata *

Redirect rule match object​

The redirect rule match object is the definition of a match in a redirect rule.

AttributeTypeRequired?Description
match_typestringYesMatch type (any of "EXACT", "UNORDERED" or "PHRASE")
patternstringYesPattern that needs to be matched against the search query

where:

  • EXACT: means that the pattern needs to match the search query exactly.
  • UNORDERED: means that all tokens in the pattern need to match the search query, but not necessarily in the same order.
  • PHRASE: means that all tokens in the pattern need to match the search query, but the search query may include additional tokens.

Create redirect rule​

To create a redirect rule, the POST method needs to be used.

Create redirect rule
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "<url>", "matches": [{"pattern": "<pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]"
Response
{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request​

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

JSON body​

The JSON body for the POST request needs to be a redirect rule object as defined in the redirect objects section.

Read all redirect rules​

To get all redirect rules, the GET method needs to be used.

Read all redirect rules
curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]"
Response
{
  "redirect_rules": [
    {
      "id": 1,
      "start_time": null,
      "end_time": null,
      "user_segments": null,
      "metadata": null,
      "url": "<url>",
      "matches": [
        {
          "id": 1,
          "match_type": "EXACT",
          "pattern": "<pattern>"
        }
      ]
    }
  ]
}

HTTP request​

GET https://ac.cnstrc.com/v1/redirect_rules?key=[your API key]

URL Parameters​

ParameterRequired?Description
keyYesThe index you'd like to to retrieve redirect rules from.
num_results_per_pageNoThe number of rules to return. Defaults to 20. Maximum value 100.
pageNoThe page of results to return. Defaults to 1. Can't be used together with 'offset'
offsetNoThe number of results to skip from the beginning. Can't be used together with 'page'
queryNoReturn redirect rules whose url or match pattern match the provided query.
statusNoOne of "current" (return redirect rules that are currently active), "pending" (return redirect rules that will become active in the future), and "expired" (return redirect rules that are not active anymore).

Read redirect rule​

To get all redirect rules, the GET method needs to be used together with a redirect rule ID passed as part of the URL.

Read redirect rule
curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"
Response
{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request​

GET https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

Update redirect rule (completely)​

To update a redirect rule completely, use a PUT method and pass the redirect rule ID as part of the URL.

Update redirect rule (completely)
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>", "matches": [{"pattern": "<new_pattern>", "match_type": "EXACT"}]}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"
Response
{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 2,
      "match_type": "EXACT",
      "pattern": "<new_pattern>"
    }
  ]
}

HTTP request​

PUT https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body​

The JSON body for the PUT request needs to be a redirect rule object as defined in the redirect objects section.

Update redirect rule (partially)​

To update part of a redirect rule, such as by changing just the target URL but not the match criteria, the PATCH method should be used together with a redirect rule ID passed as part of the URL.

Update redirect rule (partially)
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"
Response
{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request​

PATCH https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]

JSON body​

The JSON body for the PATCH request needs to be a subset of the redirect rule object as defined in the redirect objects section.

Delete redirect rule​

To delete a redirect rule, the DELETE method needs to be used together with a redirect rule ID passed as part of the URL.

Delete redirect rule
curl -X DELETE \
  -H "Content-Type: application/json" \
  -d '{"url": "<new_url>"}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]"
Response
{
  "id": 1,
  "start_time": null,
  "end_time": null,
  "user_segments": null,
  "metadata": null,
  "url": "<new_url>",
  "matches": [
    {
      "id": 1,
      "match_type": "EXACT",
      "pattern": "<pattern>"
    }
  ]
}

HTTP request​

DELETE https://ac.cnstrc.com/v1/redirect_rules/<redirect_rule_id>?key=[your API key]