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

Crawling can affect performance since it must crawl through all the items in an index. We recommend you use the Ingestion API to make frequent, small updates to a pull source index, since it is less resource heavy. In addition, you can add, edit, or delete index documents anytime.

Both manually triggered and scheduled crawls overwrite the index and you lose any updates made using the Ingestion API. To prevent this loss, remember to update your items before the next crawl.

Important

Since pull sources like crawlers do not have an initialized index by default. you need to run an indexing job with them before you use the Ingestion API to make incremental updates.

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:

  • On the menu bar, in the Developer Resources > API Access section, you can find the base URL.

  • View the Open API or swagger reference to see the detailed data model and descriptions of the objects and keys.

Ingestion API endpoints and when to you can use them.

The Ingestion API has following endpoints that 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

You can use the following endpoint to delete 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 request status

You can use the following endpoint to view the status of a request:

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 Search , 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 don't send these parameters, you won't 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,