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, or delete index documents.

Note

You can add documents to the index of a source created by an administrator. You cannot use the Ingestion API to create a source.

To use the Ingestion API to create index documents, you can pass either attributes and their values or attribute extraction logic.

There are two main use cases for the Ingestion API:

Pushing content to a pull source index

You can use the Ingestion API to make incremental updates to a pull source index. In a pull source, Search provides a crawler to crawl and index your content, but an administrator defines the logic determining what content gets indexed. Usually, pull sources have scheduled crawls that ensure indexes are up-to-date with original content. However, you can use the Ingestion API to add, edit, or delete index documents anytime. 

Important

When an administrator recrawls a pull source, either manually or through scheduled crawls, Search updates all index documents with the latest data from your original content. This action overwrites any updates you made through the Ingestion API if they aren't also applied to the original content. To prevent this, we recommend that you always update the original content with changes made through the Ingestion API. This synchronization ensures that your modifications are retained in future crawls.

Pushing content to a push source index

You can use the Ingestion API to add index documents to a push source index. In a push source, an administrator generates an empty index by creating an API push source. Then, you can use the Ingestion API to add index documents to this index.

Tip

You can use the Ingestion API along with webhooks to add or modify index documents. Webhooks are automated messages sent from apps when something happens, and they help by instantly notifying the Ingestion API of content changes, ensuring the search index is updated in real-time

Using the Ingestion API

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:

The following diagram shows endpoints the Ingestion API has, and when you can use them:

The Ingestion API has following endpoints which you can use to create, update, and delete index documents. You can also view the status of a request to the Ingestion API.

Note

In this list, {} indicates a variable you need to replace with your implementation's base URL, domain ID, source ID, entity ID, and document ID.

Creating an index document

You can use the following endpoints to create an index document:

  • Create an index document by passing attribute values - POST call to {base-URL}/ingestion/v1/domains/{domain ID}/sources/{sourceID}/entities/{entityID}/documents?locale={locale}

  • Create an index document from a file on your system by using a document extractor - POST call to {base-URL}/ingestion/v1/domains/{domainID}/sources/{sourceID}/entities/{entityID}/file/{documentID}?locale={locale}

  • Create an index document from a URL by using a document extractor - POST call to {base-URL}/ingestion/v1/domains/{domainID}/sources/{sourceID}/entities/{entityID}/url/{documentID}?locale={locale}

Updating an index document

You can use the following endpoints to update an index document:

Deleting an index document

Delete an index document - DELETE call to {base-URL}/ingestion/v1/domains/{domain ID}/sources/{sourceID}/entities/{entityID}/documents/{documentID}?locale={locale}

Viewing the status of an Ingestion API request

Check the status of request to add, update, or delete an index document  - GET call to to {base-URL}/ingestion/v1/domains/{domain}/sources/{source}/entities/{entity}/status/{incrementalUpdateId}

Authentication

If your implementation doesn't have a subdomain, you must authenticate with an API key that has the ingestion scope in order to access the Ingestion API. You can get the API key in the CEC in the Developer Resources > API Access section.

Note

You can't use an access token to authenticate calls to the Ingestion API.

Mandatory 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 attributes that are marked as required in your domain. If you don't send all the required attributes, you won't get a successful response. For example, if your domain requires the product attribute, and you don't pass product:<value> or logic to extract a value for product, Search won't create the index document.

Do you have some feedback for us?

If you have suggestions for improving this article,