Getting Started

This page describes how to get started with the AI domain of Intelligence API (Chat or Tools APIs) in a simple way using Postman.

Prerequisites

  1. You need to have a Process Copilot available in your team.
  2. You must request the activation of the API in your Celonis Platform Team to your Celonis account team.

Authentication

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

Authorization

OAuth Scopes for AI API

OAuth clients for Tools API should be configured with the scope:

  • studio

OAuth clients for Chat API should be configured with the scope:

  • intelligence.conversations:write

Client Permissions for AI API

Process Copilot access is managed by studio package permissions.

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

You can grant access permissions by following these steps:

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

Consuming the AI 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 you will 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 a AppKey

In the following example, you have an AppKey:

Postman authentication section

Chat with a Process Copilot

Once you have completed the steps above, you should now be able to start a conversation with Celonis Process Copilot. You will start by finding the Id of your Copilot from your browser as depicted here: Copilot Id

First, append "/ai/agents/" plus the node id to the URL you used in the previous steps: POST https://$team.$realm.celonis.cloud/intelligence/api/ai/agents/$copilot-id/conversations.

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

Chat API Response

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

In this quick guide, YOU managed to create your first request to AI Chat API.