Using the Ingestion API to add content to an index

Sitecore Search exposes a RESTful API called the Ingestion API that you can use to create, update, partially update, or delete index documents.

Use this API when:

you want to update index documents that are in an existing index, you don't want to for the next scheduled scan, and you don't want to manually rescan sources. To do this, use the Ingestion API and pass the ID of the source whose index contains the document you want to add or modify.

Important

When you reindex or rescan a source on the Customer Engagement Console (CEC), Search overwrites all changes you made with the Ingestion API. Because of this, after you use the Ingestion API to make updates, ensure that you go to your original content and make the update there.
you want to add or update index documents that are not in any index. To do this, an administrator first creates an API push source on the Customer Engagement Console (CEC). This creates an index. Then, you can use the Ingestion API to add or modify documents.

To create index documents, pass attributes and their values as key:value pairs in the body of the request. You can only pass values for attributes that are defined in the Administration > Domain Settings > Attributes section of the CEC.

You can use webhooks along with the Ingestion API to push content to a Search index.

Sitecore Search supports the HTTPS protocol for the Ingestion API. The API accepts requests in the form of JSON objects. To help you work with the Ingestion API, you can view the detailed data model and descriptions of the objects and keys.

Prerequisites

Before you use the Ingestion API to create, update, or delete index documents, an administrator must

Create and publish a source in the Customer Engagement Console (CEC). You will use the ID of this source in Ingestion API calls.
Turn on ENABLE INCREMENTAL UPDATES in the CEC for the source you created.

Note

This prerequisite does not apply if your source is an API push source.

API URL and methods

You can get the base API URL in the Customer Engagement Console (CEC), in the Developer Resources > API Access section.

The Ingestion API supports different methods based on the endpoint you want to call:

Authentication

If you do not have a subdomain, you must authenticate with an API key to access the Ingestion API. You can see your API key in the Developer Resources > API Access section of the CEC.

The API key you use must have the ingestion scope.

Note

You cannot use an access token to authenticate calls to the Ingestion API.

Parameters

When you send requests to the Ingestion API, there are two types of mandatory parameters:

Parameters that are mandated by the data model. All endpoints require the domain, source , and entity parameters. Some endpoints require other mandatory parameters. See the detailed data model and descriptions of the objects and key. If you do not send these parameters, you do not get a successful response.
Parameters for values of attributes that are marked as required in your domain. If you do not send all required attributes, you do not get a successful response. For example, if your domain has the product attribute as required, and you do not pass product:<value>, Search does not create the index document.

Sample request

Here's a sample POST CURL request to the Ingestion API to create a new index document for the English (US) locale:

RequestResponsecurl

curl --location 'https://<base-url/domains/<domainID>/sources/<sourceID>/entities/<entity>/documents?locale=<locale>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <api-key>' \
--data '{
    "document": {
        "id": "test_id_123",
        "fields": {
            "title": "Test blog"
            "description": "This is an awesome blog",
            "type": "blog",
            "url": "www.someURL.com"
        }
    }
}'

Note

In this example, you can pass values for title, description, and type because these attributes are defined in the CEC.

Do you have some feedback for us?

If you have suggestions for improving this article,