Getting Started

This page describes how to get started with the Subscription API in a simple way using Postman.

Prerequisites

  1. You need to have a Knowledge Model available in your team with at least one KM Trigger .
  2. You must request the activation of the API in your Celonis Platform Team to the account team.

Authentication

The authentication options applicable to all Celonis APIs are described here.

Authorization

You must set the right permissions and ensure the User API Key or the Application leveraged for authorization purposes has access to the Celonis Celonis Platform Studio package containing the Knowledge Model(s) and the Triggers you would like to access through Subscription API.

You can grant access permissions by following these steps:

  • Go to the Studio package.
  • Click on the three dots and select Permissions from the pop-up menu.
  • Search for the User (in case you are using a Bearer token ) the Application (in case you are using an AppKey ) and grant at least USE PACKAGE and EDIT PACKAGE rights.

OAuth Scopes used by Subscription API

  • OAuth Scope:
    • studio

Consuming the Subscription API

Once you have completed the previous steps, you can start making requests to the API. For that you will use Postman (or any other REST client), which you should already have installed in our system.

  1. Go to File > New... and select "HTTP Request". Once you do this, you should see something like this:

Postman empty request

  1. Enter the request URL next to the Send button. For this URL use the one from the "Determine the URL for your team" section: https://dev.us-2.celonis.cloud/intelligence/api .
  2. Now you need to set your API or Application Key in order to authenticate our requests. To do this, click on the Headers tab beneath the URL you just entered. Enter "Authorization" as the Key and for Value, enter:
  3. Bearer <YOUR_KEY> if you have a User API Key
  4. AppKey <YOUR_KEY> if you have an AppKey

In the following example, you have an AppKey:

Postman authentication section

Getting the list of Knowledge Models

Once you have completed the steps above, you should now be able to start getting some data. You will start getting the full list of Knowledge Models to which your API token has access.

First, append "/knowledge-models" to the URL used in the previous steps: https://dev.us-2.celonis.cloud/intelligence/api/knowledge-models.

After that, click the Send button next to the URL and you should see something like:

Knowledge Models response

Inside the Content section, you will see a list of all your Knowledge Models. The Knowledge Models will be divided into pages. By default, the page size will be 50. If you have more than 50 Knowledge Models, you can navigate to the following page, adding a "page" query parameter. The pages start at 0, so you can display the second page by setting a page value of 1.

Setting a page query parameter

In this example, this is not needed as we only have 13 Knowledge Models. However, you might want to specify other query parameters such as:

  • pageSize : Sets the size of each page.
  • sort : Sort the results by id or name.

You can check the full list of parameters and possible responses from this page.

You can also check the full list of possible errors you can receive in the API, in case you need to troubleshoot any issue.

Getting the list of KM Triggers

You will now get the list of Triggers in a selected Knowledge Model to which your API token has access.

First, append "/{knowledge-model-id}/triggers" to the URL used in the previous steps: https://dev.us-2.celonis.cloud/intelligence/api/knowledge-models/{knowledge-model-id}/triggers.

After that, click the Send button next to the URL and you should see something like: Triggers Response

In this quick guide, you managed to create your first requests to Subscription API and discover the triggers to which consumers can subscribe.

Please refer to the guidelines for subscription lifecycle management for more details and tutorials.