Push API tutorials

This is for:

Developer System Administrator
In this article

This section contains introductory, intermediate, and advanced Push API tutorials.

These tutorials assume that the reader knows how to make HTTP requests, and is familiar with REST interfaces and microservices in general.

Tutorial setup

The tutorial setup consists of three mandatory requirements and one optional recommendation:

The dedicated Coveo organization

You need a dedicated Coveo organization in which you have administrator privileges. This Coveo organization will contain the Push source and will be used to perform all Push API HTTP requests in the tutorials.

You can create a free trial organization for this purpose.

Note your organization ID as you’ll need it for the Push API requests. It appears in the URL when you’re in your organization.

Getting the organization ID from the URL | Coveo
Note

Your trial organization will be hosted in the US East deployment region. You may create a free test organization within your trial organization, should you prefer testing the Push API on another deployment region supported by Coveo.

The public content Push source

When you index content using the Coveo Push API, the created items are associated with a Push source. For the first tutorial, you’ll need a public content Push source.

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

  2. Click Add source.

  3. In the Add a source of content panel, select Push.

  4. Name your source.

  5. Click Add source.

  6. In the Make content accessible to everyone? dialog, check I understand and click Continue. This will make your source content public. In tutorial 2, you’ll edit the source to secure its content.

  7. Note your source ID as you’ll need it for the Push API requests.

    Getting the source ID | Coveo

The API key

The API key will grant you the privileges required to perform all Push API HTTP requests in the tutorial. The content of your Push source is public for the first tutorial, but you’ll need to secure it in the second tutorial. Consequently, we’ll immediately create a custom API key that grants you the required privileges for all three tutorials, instead of using one of the dedicated Push source API key creation methods.

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

  2. Click Add key.

  3. In the Add an API key panel, select the Custom template, and then click Next.

  4. Name your key, and then click Next.

  5. In the Privileges tab, grant the following privileges:

    • Content - Push items to sources - Custom - Allow (only on your new source)

    • Content - Push identities to security providers - Allow for all providers

    • Content - Sources - View

    • Content - Security identity providers - View

    • Organization - Organization - View

      Note

      The privileges listed above are the same as those granted automatically when creating an API key specifically for a secured content Push source.

  6. Click Next until you reach the Review screen.

  7. Click Add API key.

  8. Click clipboard-text to copy the key to your clipboard and store it securely. You’ll need it for the Push API requests.

The Coveo Push API Tutorials Postman collection JSON file contains all Push API HTTP requests used in the tutorials. The requests are ordered sequentially and grouped into folders that correspond to the three tutorials. The request payloads are set, and collection variables are used to store values that are repeatedly used in requests. The collection also contains pre-request and post-response scripts to help prevent common errors and speed up request execution.

  1. Download the Coveo Push API Tutorials Postman collection

  2. In your Postman workspace, import the Coveo Push API Tutorials collection JSON file.

  3. In your Postman workspace, set the appropriate value for the baseUrl collection variable, depending on your Coveo organization region.

    • For the US region, set it to https://api.cloud.coveo.com.

    • For the EU region, set it to https://api-eu.cloud.coveo.eu.

    • For the CA region, set it to https://api-ca.cloud.coveo.ca.

    • For the AU region, set it to https://api-au.cloud.coveo.com.au.

  4. Set the values for the organizationId, sourceId, and apiKey collection variables that you noted earlier.

    Tip

    To protect your API key, we recommend creating and using an environment variable named apiKey in Postman and setting its type to Secret.

    Postman automatically uses environment variables over collection variables when they have the same name. This way, your sensitive Coveo API key stays safe.

The value of the securityIdentityProviderId variable is set in the collection JSON file. This is intentional, as you’ll see later on.

The tutorials will inform you, in note boxes with the Postman icon Postman logo, whenever you need to set variable values or when you need to be aware of collection automations working in the background.

What’s next?

You’re ready to start the tutorials. You should do the three tutorials sequentially, as the outcome of one tutorial may be used as a prerequisite for the next one.

Proceed to Push API tutorial 1: Manage public content.