Variations

Create or replace variations

By using the following method you can add variations to Krestor or replace data of existing ones. Variations match by id and item_id.

Shell

curl -X PUT -H "Content-Type: application/json" \
-d '{
        "variations": [
            {
                "id": "nike-shoes-brown-low-top",
                "item_id": "nike-shoes-brown",
                "name": "Nike Shoes Brown Low Top",
                "data": {
                    "facets": {
                        "Model": ["Low-Top"]
                    }
                }
            },
            {
                "id": "nike-shoes-brown-high-top",
                "item_id": "nike-shoes-brown",
                "name": "Nike Shoes Brown High Top",
                "data": {
                    "facets": {
                        "Model": ["High-Top"]
                    }
                }
            }
        ]
    }'\ -u"[your token]:" "https://ac.cnstrc.com/v2/variations?key=[your API key]&section=[section_name]"

JavaScript

// This method is not currently supported.

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

info

The above command returns a 200 Success response on success.

HTTP Request

PUT https://ac.cnstrc.com/v2/variations?key=[your API key]&force=False&notification_email=[your email for notifications]&section=[section_name]

URL Parameters

Attribute	Type	Required?	Description
key	string	yes	The API key of the index that you'd like to make changes to.
force	boolean	No	Process the request even if it will invalidate a large number of existing variations. Defaults to False.
notification_email	string	No	An email address where you'd like to receive an email notification in case the task fails.
section	string	No	Your autosuggest and search results can have multiple sections like "Products" and "Search Suggestions". This indicates which section this item is for. See your dashboard for the section names to use.

JSON Parameters

Request top level parameters

Parameter	Type	Required?	Description
variations	array of objects	Yes	Array of variations you want to create/update. Schema for a single variation is defined in Variation schema. You can create/update up to 1000 variations in a single request.

Variation schema

Parameter	Type	Required?	Description
id	string	Yes	The id of the variation, must be unique. The maximum length is 250 characters.
item_id	string	Yes	The id of the item this variation is attached to.
name	string	Yes	The name of the variation, as it will appear in the results. The maximum length is 250 characters.
suggested_score	float	No	A number between 1 and 100 million that will influence the variation's initial ranking relative to other variation scores (the higher the score, the higher in the list of suggestions the variation will appear).
data	object	Yes	Object containing additional data, that should be attached to this variation. Schema for data is defined in Variation data schema. Maximum size of data object is limited to 100kb.

Variation data schema

Parameter	Type	Required?	Description
keywords	array of strings	No	An array of keywords for this variation. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
url	string	Yes	A URL to directly send the user after selecting the variation. Might not be required in some cases. Please contact support@Krestor if you have questions around that.
image_url	string	No	A URL that points to an image you'd like displayed next to some variation (only applicable when url is supplied).
facets	object	No	Key/value pairs that can be associated with an variation and used to filter them during a search. You can associate multiple values with the same key. Facets can be used as filters in search, autosuggest, and browse requests.
group_ids	array of strings	No	You can associate each variation with one or more groups (i.e. categories). To set up a group hierarchy please contact support@Krestor group_ids can be used as filters in search, autosuggest, and browse requests.
description	string	No	A description for some variation (only applicable when url is supplied). The maximum length of this field is 250 characters.
any other keys	any	No	You can also provide any other information you want to associate with that variation. No special validation is made for that data.

Update variations

In addition to above method, this one can be used to update existing variation data. Data from the request will be merged with data of the existing variation.

Shell

curl -X PATCH -H "Content-Type: application/json" \
-d '{
        "variations": [
            {
                "id": "nike-shoes-brown-low-top",
                "item_id": "nike-shoes-brown",
                "data": {
                    "url": "https://nike.com/new-shoes-brown-low-top-url.html"
                }
            },
            {
                "id": "nike-shoes-brown-high-top",
                "item_id": "nike-shoes-brown",
                "name": "Nike Shoes Brown High Top New Name"
            }
        ]
    }'\ -u"[your token]:" "https://ac.cnstrc.com/v2/variations?key=[your API key]&section=[section_name]"

JavaScript

// This method is not currently supported.

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

HTTP Request

PATCH https://ac.cnstrc.com/v2/variations?key=[your API key]&force=False&notification_email=[your email for notifications]&section=[section_name]

URL Parameters

URL parameters are the same as for Create or replace variations

JSON Parameters

JSON parameters are the same as for Create or replace variations. The only difference is that name and data.url in Variation schema are not required when updating already existing variations.

Retrieve Variations

Retrieves all variations for the given key and section, paginated by num_results_per_page, optionally filtered by id and/or item_id. Multiple ids represent an OR request, returning results including any of the provided ids. If item_id is specified it is used as additional AND filter, only one item_id is accepted in query parameters. You can request all variations of an item by sending request with corresponding item_id and without any id parameters.

If id is specified in the URL, the endpoint returns just the item with that id.

Shell

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]"

JavaScript

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]&id=1&id=2"

Python

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations/?key=[your index key]&section=[section_name]&item_id=123"

Java

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations/?key=[your index key]&section=[section_name]&item_id=123&id=1&id=2"

iOS

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations/1?key=[your index key]&section=[section_name]"

Android

// This method is not currently supported.

C#

# This method is not currently supported.

// This method is not currently supported.

// This method is not currently supported.

// This method is not currently supported.

// This method is not currently supported.

HTTP Requests

GET https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]

GET https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]&id=[id]&id=[id]

GET https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]&item_id=[id]

GET https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]&item_id=[id]&id=[id]&id=[id]

GET https://ac.cnstrc.com/v2/variations/[id]?key=[your index key]&section=[section_name]

Response format

{
  "variations": [
    {
      "id": "[variation_id]",
      "item_id": "[item_id]",
      "name": "[variation_name]",
      "suggested_score": "[variation_score]",
      "data": {[variation_metadata]},
    },
    {
      "id": "[another_variation_id]",
      "item_id": "[another_item_id]",
      "name": "[another_variation_name]",
      "suggested_score": "[another_variation_score]",
      "data": {[another_variation_metadata]},
    }
  ],
  "total_count": "[number_of_variations]"
}

URL Parameters

Parameter	Description
id	The id of the variation you'd like to retrieve.

Query Parameters

Parameter	Required?	Description
key	Yes	The index you'd like to to retrieve results from.
section	Yes	The index section you'd like to retrieve results from.
id	No	Id(s) of variations to return. Maximum number of ids to request is 1000.
item_id	No	Item id of variations to return.
num_results_per_page	No	The number of variations to return. Defaults to 100. Maximum value 100.
page	No	The page of results to return. Defaults to 1.

Delete Variations

For the given key and section deletes variations filtered by id.

Shell

curl -X DELETE -H "Content-Type: application/json" \
  -d '{"variations": [ {"id": "nike-shoes-brown-low-top"}, {"id": "nike-shoes-brown-high-top"} ]}' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]"

JavaScript

// This method is not currently supported.

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

HTTP Requests

DELETE https://ac.cnstrc.com/v2/variations?key=[your index key]&section=[section_name]

info

The above requests return a 200 Success response on success.

Query Parameters

Parameter	Required?	Description
key	Yes	The index you'd like to to delete variations from.
section	Yes	The index section you'd like to delete variations from.

JSON Parameters

Request top level parameters

Parameter	Type	Required?	Description
variations	array of objects	Yes	Array of variations you want to delete. Each object of the array should have only id field as described below. You can delete up to 1000 variations in a single request.

Variation delete schema

Parameter	Type	Required?	Description
id	string	Yes	The id of the variation, must be unique. The maximum length is 250 characters.