Calling the Search and Recommendation API

API URL and methods

You can get the API URL in Sitecore Search, in the Developer Resources section, on the API Access tab.

Use the POST method to send requests to the Search and Recommendation API.

Authentication

You must authenticate to access Sitecore Search REST APIs. Use an API key or access token in the request header.

Mandatory objects

When you send requests to the API, you must include these objects to get a response:

• rfk.domainId - add this to the header of your request to specify the domain for which you want to make the request.
• widget.items.rfkd_id - add this key to specify the rfkid of the widget you want to call.
• widget.items.entity - add this key to specify the entity you want to use for this request.
• context.locale - If you have a multi-locale domain, add this object to specify the country and language you want to use for the results.

Recommended object

When you send requests to the API, we recommend that you add the following object:

• context.user.uuid - an anonymous unique identifier of the visitor who visits the page. Add this object so that Sitecore Search can give your visitors relevant search results. If you do not pass the uuid, the search results you see are not tailored to that specific visitor. To learn how to generate a uuid, see Using a UUID to track site visitors.

Sample request

The following is a sample POST request to the Search and Recommendation API to get content for the key phrase cloud computing:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "content": {},
                    "query": {
                        "keyphrase": "cloud computing"
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        }
        "user": {
      	    "uuid": "string" //or "user_id": "string" if your uuid does not follow the example here (https://doc.sitecore.com/search/en/developers/search-developer-guide/using-a-uuid-to-track-site-visitors.html)"uuid": "string"
        }
    }
}

Error Codes

The following table lists common errors that you might encounter when calling Sitecore Search APIs with an API key or access token.

Table 1. Error Codes