Use the Push API

This is for:

Developer System Administrator

The Push API is a REST API that you can use to index content into a Coveo organization by sending items directly to Coveo, rather than relying on a Coveo crawler to retrieve them. Each request targets a source you manage, and you control the full lifecycle of your indexed content: when items are added, updated, or deleted, and which security identities can access them.

With the Push API, you can 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. Use the Push API when you need full control over what gets indexed and when, for example, your content lives in a custom or proprietary system that Coveo can’t crawl directly.

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

How the Push API fits within your system

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

Push API interaction diagram | Coveo

When to use the Push API

Use the Push API when:

  • Your content lives in a custom or proprietary system with no native Coveo connector.

  • You need precise control over indexing timing, for example, to trigger updates immediately after content changes in your system.

  • You want to manage item permissions programmatically rather than relying on a source-level security configuration.

Note

If your use case involves high-volume catalog data updates in a Catalog source, consider the Stream API instead. The Stream API is optimized for commerce catalog workflows, including full and partial updates.

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 started and guide you toward a successful project implementation.

Plan your project

Read the Custom connector planning guide for best practices and resources to help you get started and reduce development and troubleshooting 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, unless you’re performing Delete old items or 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.

With batch updates, you can keep your Push API requests per hour relatively low. See Push API quotas and constraints 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, INCREMENTAL, or REFRESH, as appropriate. After completing the indexing process, set the status back to IDLE.

Updating your Push source status helps you keep consistent source activity logs in your Coveo organization.

Troubleshooting

A successful Push API response only confirms that the request was accepted for processing—it doesn’t guarantee that the operation was completed successfully. Failures can still occur downstream in the Coveo indexing pipeline. For example, an item may be rejected due to validation rules or unsupported content. Many downstream failures can only be observed through the Log Browser (platform-ca | platform-eu | platform-au) in the Coveo Administration Console.

Log Browser showing permissions error | Coveo

See Troubleshooting Push source issues for complete troubleshooting.

Important

For Push API source and security identity operations, the only visibility on the Coveo side is what’s available in the Log Browser (platform-ca | platform-eu | platform-au); Coveo doesn’t retain additional logs for these operations beyond that. Coveo Support will require customer-side logs to provide Push API assistance. Coveo Support expects, at the very least, response codes to be logged.

For suggested logging practices, see the Custom connector planning guide.

What’s next

Learn more about the Push API with a usage example to help get you started.