---
title: Use the Push API
slug: '68'
canonical_url: https://docs.coveo.com/en/68/
collection: index-content
source_format: adoc
---
# Use the Push API
The Push API exposes services that let you _push_ [items](https://docs.coveo.com/en/210/) and their [permission models](https://docs.coveo.com/en/225/) into a [source](https://docs.coveo.com/en/246/), and [security identities](https://docs.coveo.com/en/240/) into a [security identity provider](https://docs.coveo.com/en/242/), 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](https://docs.coveo.com/en/185/).


![Push API interaction diagram | Coveo](https://docs.coveo.com/en/assets/images/index-content/push-api-diagram.png)

## Prerequisites

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

. A Push source.

. A security identity provider, if your Push [source](https://docs.coveo.com/en/246/) is secured.

. Fields to receive the [metadata](https://docs.coveo.com/en/218/) you want to push.

See the [Push source creation](https://docs.coveo.com/en/1546#add-a-push-source) and [post-creation](https://docs.coveo.com/en/1546#whats-next) steps for detailed instructions.

## Push API usage

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

* [Add, update, or disable security identities, if applicable](https://docs.coveo.com/en/132/).

* [Add, update, or delete items, along with their metadata and permissions, if applicable](https://docs.coveo.com/en/70/).

* [Update the source status](https://docs.coveo.com/en/35/).

## 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](https://docs.coveo.com/en/3379/) 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:

* The [Push API usage example](https://docs.coveo.com/en/1336/) and [tutorials](https://docs.coveo.com/en/161/), for a guided experience.

* The [Push API reference](https://docs.coveo.com/en/78/), for a complete list of available requests.

* Your region-specific Swagger UI ( [US](https://platform.cloud.coveo.com/docs?urls.primaryName=PushAPI)   |  [EU](https://platform-eu.cloud.coveo.com/docs?urls.primaryName=PushAPI)   |  [AU](https://platform-au.cloud.coveo.com/docs?urls.primaryName=PushAPI)   |  [CA](https://platform-ca.cloud.coveo.com/docs?urls.primaryName=PushAPI) ), for interactive reference documentation.

* The [Troubleshooting Push source issues](https://docs.coveo.com/en/95/) article, for common problems and solutions.

### 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](https://docs.coveo.com/en/246/).
Otherwise, you risk causing irreparable damage to your [index](https://docs.coveo.com/en/204/).

### Avoid setting orderingId values

Let the service set the [`orderingId`](https://docs.coveo.com/en/147/) value automatically, except when performing [`Delete old items`](https://docs.coveo.com/en/131/) and [`Delete old security identities`](https://docs.coveo.com/en/33/) requests.

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

### Prioritize batch updates

Only use single [item](https://docs.coveo.com/en/210/) and [security identity](https://docs.coveo.com/en/240/) requests when testing or performing small updates.
Use [batch item](https://docs.coveo.com/en/90/) and [batch security identity](https://docs.coveo.com/en/55/) 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](https://docs.coveo.com/en/63/) for details.

### Update your Push source status

Consider [updating the status](https://docs.coveo.com/en/35#update-the-status-of-a-push-source) 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](https://docs.coveo.com/en/173/) logs in your [Coveo organization](https://docs.coveo.com/en/185/).

## Troubleshooting

> **Note**
>
> 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](https://docs.coveo.com/en/184/).
> 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**](https://platform.cloud.coveo.com/admin/#/orgid/logs/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/logs/browser/)) in the [Coveo Administration Console](https://docs.coveo.com/en/183/).
> 
> ![Log Browser showing permissions error | Coveo](:https://docs.coveo.com/en/assets/images/index-content/log-browser-example.png)
> 
> For complete troubleshooting guidance, see the [Troubleshooting Push source issues](https://docs.coveo.com/en/95/) article.