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.

Optionally, use the Run in Postman shared HTTP requests. If you do, set the appropriate values for the organizationId and apiKey environment variables in Postman in order for the API requests to execute successfully (see Manage Globals).

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 own Push sources. This means that when you plan to perform a set of Push API operations to update the content of a Push source, you should first update the status of that source accordingly.

Use the POST /status HTTP request to set the status of your public Push source to REBUILD.

If you navigate to the Sources (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you should now see that the status of your Push source changed 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 subsequent Push API tutorials.

Step 2: Add an item to your source

Use the PUT /sources/{sourceId}/documents HTTP request to add the following dummy item to your public Push source.

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

When pushing the above item, set the documentId query parameter to file://folder/dummyItem.txt. This URI doesn’t actually reference an existing item, but this doesn’t matter as you’re merely pushing fictitious content.

Important

When you use the Push API to manage items in a source, the service doesn’t directly add, update, or delete content in your index. The Push API simply forwards the required operations to the document processing manager (DPM). This means that:

  • Using the Push API involves some processing delays. You may have to wait a few minutes before the item you added becomes available in your source.

  • A successful Push API call response doesn’t guarantee that the required operations will be fully processed by the DPM. For example, an item can be rejected. You then need to troubleshoot the issue.

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.

Step 4: Remove the item from your source

To start the Push API tutorial 2: Manage secured content with a clean source, use the DELETE /sources//documents HTTP request to delete the item you added in step 2.

Note

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

As you did in step 3, use the Content Browser (platform-ca | platform-eu | platform-au) to validate that the item has been deleted from your source before proceeding to the next step of this tutorial.

Step 5: (Optional) Generate more source activity logs

Now that your source content update is complete, use the POST /status HTTP request to set the status of your public Push source back to IDLE. On the Sources (platform-ca | platform-eu | platform-au) page, you should now see that the source status is Ready to receive content.

Source Status is "Ready to receive content"

If you don’t perform this status update, the source status will remain Retrieving content indefinitely.

What’s next?

Proceed to Push API tutorial 2: Manage secured content.