Use the Push API

This is for:

Developer System Administrator

The Push API exposes services that let you push items and their permission models into a source, and security identities into a security identity provider, rather than letting standard Coveo crawlers pull this content.

The Push API doesn’t have a graphical user interface, so you must perform your own HTTP requests to use its services.

The articles in this section explain how to use the Push API.

Architecture diagram

The following diagram shows the main interactions between a custom crawler, the Push API, and a Coveo organization.

Push API interaction diagram | Coveo

Prerequisites

To index content using the Push API, you need the following:

  1. A Push source.

  2. A security identity provider, if your Push source is secured.

  3. Fields to receive the metadata you want to push.

See the Push source creation and post-creation steps for detailed instructions.

Push API usage

After completing the setup covered in the prerequisites section, you can use the Push API. This involves writing code that will run periodically to:

Getting started and beyond

The Coveo Push API is a powerful tool, but it can be complex to use. The following recommendations will help you get up and running quickly—and guide you toward a successful project implementation.

Plan your project

Read the Custom connector planning guide article for best practices and resources to help you get started and reduce development time.

Use the resources at your disposal

Refer to the following resources for help:

Avoid performing Push API requests on product-managed sources

Never perform Push API requests to interact directly with Coveo Crawling Module or Coveo for Sitecore Push sources. Otherwise, you risk causing irreparable damage to your index.

Avoid setting orderingId values

Let the service set the orderingId value automatically, except when performing Delete old items and Delete old security identities requests.

If you have a good reason for setting your own orderingId values, proceed with caution.

Prioritize batch updates

Only use single item and security identity requests when testing or performing small updates. Use batch item and batch security identity update requests the rest of the time.

Using batch updates allows you to keep your number of Push API requests per hour relatively low. See Push API limits for details.

Update your Push source status

Consider updating the status of a Push source before and after each set of content update requests.

For example, before you begin indexing new or updated content, set the source status to REBUILD, RESCAN, or REFRESH, as appropriate. After completing the indexing process, set the status back to IDLE.

Updating your Push source status allows you to keep coherent source activity logs in your Coveo organization.

Troubleshooting

Push API operations can fail at different stages of the process: