Start your content search
3 min read

Index your feed directly using the Index API

The Index API is the main entry point for any interaction required with the feed indexing process.

interact

The Index section of the Playboard's Instance Management Console is the user-friendly foreground for directly interacting with the feed indexing process.

Consuming the Index API

There are several ways to consume an API. Here are the most common ways.

interact

Remember that you can get the Index API YAML file from the API Reference.

cURL

This is the most basic way of interacting with the API. You only need a terminal. With just the following command, you can submit a job to index a catalog-type feed:

curl --request POST \
  --url https://{HOST}/jobs/submit/empathy/{CLIENT_TOKEN}/catalog \
  --header 'Content-Type: application/gzip' \
  --data '@{FEED_FILE_PATH}'

Where:

  • HOST is the host of the environment you are working on.
  • CLIENT_TOKEN is the token of the client for which you want to index the feed. This is a unique identifier for each client and can be obtained from the Index API as well. Follow the instructions of the Getting the client token section if you don't have your client token yet.
  • FEED_FILE_PATH is the path in your local machine where the feed file you want to index is located.

Here is only one example of how to submit a feed file.

Getting the client token

The request to obtain the client token (CLIENT_TOKEN) is the following:

curl --request GET \
  --url https://{HOST}/clients/empathy \
  --header 'Authorization: Bearer {ACCESS_TOKEN}'

warning

The value for ACCESS_TOKEN is obtained from the authentication endpoint. To learn how to get it, check the Getting the access token section.

The value you want to take from the response is the token field. You will need this value for almost every request made to the Index Pipeline API.

Getting the access token

The access token (ACCESS_TOKEN) is widely utilized across Empathy's services to authorize the user, application, or service that makes the request. Although there are several ways to get the access token, the preferred one is service-to-service authorization.

Service-to-service authorization

When a service needs to get authorization on its own, not on behalf of a user, it can make use of the oauth2 token endpoint following the OAuth 2.0 standard's client credentials flow as follows:

curl --request POST \
  --url https://{HOST}/oauth/token \
  --header 'Authorization: Basic {BASIC_TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form grant_type=client_credentials

Where:

  • HOST is the host of the OAuth2 service for the environment you are working on.
  • BASIC_TOKEN is the base64 encoded string of the client ID and client secret. Where client ID and client secret are the credentials of the service that is making the request.

Once the service makes the request, it must take the access_token value from the response and use it when needed.

API clients

API clients are a more user-friendly way of interacting with the Index API. The two more common clients used at Empathy.co are Insomnia (opens new window) and Postman (opens new window).

Below, you find how to import the API specifications in both of them to start using the API. You can get the Index API YAML file from the API Reference. Then, follow the steps in each case to import the collection for your client.

Cookie-Less