Push API tutorial 1: Manage public content

This is for:

Developer System Administrator

For this tutorial, you’ll be working with a public Push source. Any user who can perform queries in a Coveo organization can see the items of a public source in their query results.

You’ll add a single basic item to your public Push source and then delete it. You’ll also learn how to update the status of a Push source to generate coherent activity logs.

Prerequisites

You need the setup described in the Push API Tutorials article.

Step 1: (Optional) Generate your first source activity logs

For non-Push sources, the Coveo crawlers automatically take care of generating activity logs in your Coveo organization. However, you’re fully responsible for managing the activity logs of your Push sources. When you plan to make Push API requests to update the content of a Push source, update that source’s status first.

You’ll now send a Set the status of a Push source request to set the status of your Push source to REBUILD.

  1. In your preferred HTTP client, create a new POST request using the Push API endpoint corresponding to your deployment region.

    US East region 
    POST https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Canada region 
    POST https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Ireland region 
    POST https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Australia region 
    POST https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}

  2. Configure the request.

    Postman

    You should have set the proper values for the following Postman collection variables during the setup:

    • baseUrl

    • organizationId

    • sourceId

    • apiKey

    The statusType parameter and its value are specified in the endpoint URL query string.

    All the necessary variables should therefore already be set for this request.

    • Set the organizationId and sourceId path parameters to the values you noted in the Push API Tutorials setup article.

    • Set the statusType query parameter value to REBUILD.

    • Use your API key as the Authorization header accessToken value.

  3. Send the request.

On the Sources (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, after the processing delay, you should see that the status of your Push source change from Ready to receive content to Retrieving content.

Note

Typically, you shouldn’t bother to update the status of a Push source when you’re only performing tests, which is why this tutorial step is optional.

You won’t be asked to generate source activity logs in the next tutorials.

Step 2: Add an item to your source

You’ll now send an Add or update an item request to add a dummy item to your Push source.

  1. In your HTTP client, create a new PUT request using the Push API endpoint corresponding to your deployment region.

    US East region 
    PUT https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
    Canada region 
    PUT https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
    Ireland region 
    PUT https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
    Australia region 
    PUT https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}

  2. Configure the request.

    Postman

    In the Coveo Push API Tutorials collection, all the necessary variables and payload have already been set for this request.

    • Set the organizationId and sourceId path parameters to the values you noted in the Push API tutorials setup article.

    • Use your API key as the Authorization header accessToken value.

    • Set the documentId query parameter value to file://folder/dummyItem.txt. This URI doesn’t reference an existing item, but that’s acceptable since you’re only pushing fictitious content.

    • Use the following JSON as your request body.

      {
  "data": "This is a dummy item."
}

  3. Send the request.

You should receive a 202 response, but you may have to wait a few minutes before the item you added becomes available in your source.

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. 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

For complete troubleshooting guidance, see the Troubleshooting Push source issues article.

Step 3: Validate the indexing status of the item

To validate whether the item you added in step 2 has been processed successfully, you’ll now use the Content Browser (platform-ca | platform-eu | platform-au) (see Inspect items with the Content Browser).

  1. In the Coveo Administration Console, access the Sources (platform-ca | platform-eu | platform-au) page.

  2. On the Push source row, click Open in Content Browser.

    Show source items in the Content Browser

If you see the item in the Content Browser after the processing delay, move on to the next step of this tutorial.

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. 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

For complete troubleshooting guidance, see the Troubleshooting Push source issues article.

Step 4: Remove the item from your source

To begin Push API tutorial 2: Manage secured content with a clean source, you’ll now send a Delete an item and optionally its children request to remove the item you added in step 2.

  1. In your HTTP client, create a new DELETE request using the Push API endpoint corresponding to your deployment region.

    US East region 
    DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId}&deleteChildren=true|false HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Canada region 
    DELETE https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId}&deleteChildren=true|false HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Ireland region 
    DELETE https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId}&deleteChildren=true|false HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Australia region 
    DELETE https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId}&deleteChildren=true|false HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}

  2. Configure the request.

    Postman

    In the Coveo Push API Tutorials collection, all the necessary variables have already been set for this request.

    • Set the organizationId and sourceId path parameters to the values you noted in the Push API Tutorials setup article.

    • Use your API key as the Authorization header accessToken value.

    • Set the documentId query parameter value to file://folder/dummyItem.txt.

      Note

      You don’t need to include the deleteChildren query parameter in your request. The deleteChildren parameter’s default value is false.

  3. Send the request.

You should receive a 202 response.

As in step 3, use the Content Browser (platform-ca | platform-eu | platform-au) to confirm that the item has been deleted from your source. You can then proceed to the next step of this tutorial.

Step 5: (Optional) Generate more source activity logs

Your source content update is complete so you’ll now use the Set the status of a Push source request to set the status of your Push source back to IDLE. If you don’t perform this status update, the source status in the Coveo Administration Console will remain Retrieving content indefinitely.

  1. In your HTTP client, create a new POST request using the Push API endpoint corresponding to your deployment region.

    US East region 
    POST https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Canada region 
    POST https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Ireland region 
    POST https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
    Australia region 
    POST https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}

  2. Configure the request.

    Postman

    In the Coveo Push API Tutorials collection, all variables that this request requires are already set.

    • Set the organizationId and sourceId path parameters to the values you noted in the Push API Tutorials setup article.

    • Set the statusType query parameter value to IDLE.

    • Use your API key as the Authorization header accessToken value.

  3. Send the request.

On the Sources (platform-ca | platform-eu | platform-au) page, after the processing delay, you should see the source status return to Ready to receive content.

Source status is Ready to receive content | Coveo Platform

What’s next?

Proceed to Push API tutorial 2: Manage secured content.