# Knowledge Model API

This documentation describes how to interact with the Celonis Knowledge Model REST API.

## Goals

The Knowledge Model API allows customers to embed actionable intelligence into third-party platforms where end-users may benefit from Celonis insights. In this manner, we would bring Celonis intelligence closer to our end-users and benefit operational users without current access to Celonis by providing valuable insights for better decision-making while executing their day-to-day activities.

The current API methods allow consumers to interact with Knowledge Models defined in the Celonis Platform by providing the following functionalities:

* **Discover** Celonis knowledge structure (organized in a process context entity - Knowledge Model):
  * *Records* (data structures, either auto-generated, i.e. tables, or curated i.e. views)
  * *KPIs* (metrics measuring process efficiency and value)
  * *Filters* (business condition criteria)
  * *Triggers* (events indicating the occurrence of a business condition)
* **Query** Celonis knowledge data:
  * across all records of a knowledge model
  * a specific record of a knowledge model


## How it works

In order to understand Celonis Knowledge structure, you need to use the Knowledge Model API discovery end-points first.

Celonis knowledge is organized in Knowledge Models which represent a process context (use case) related to a specific process and can be browsed iteratively.
Refer to our [glossary](/process-intelligence-apis/knowledge-model-api/glossary) to understand the Celonis Knowledge concepts better.


```mermaid
erDiagram
          Knowledge_Model ||--|{ Filter: contains
	  Knowledge_Model {
        	string id
        	string name
        	datetime published
          }
	  Filter {
        	string id
        	string name
        	string description
          }
          Knowledge_Model ||--|{ KPI: contains
	  KPI {
        	string id
        	string type
        	string format
        	string unit
        	string name
        	string direction
        	string target
        	string parameters
          }
          Knowledge_Model ||--|{ Record: contains
	  Record {
        	string id
        	string name
        	string description
        	string shortDisplayName
        	string internalNote
          }
          Knowledge_Model ||--|{ Trigger: contains
	  Trigger {
        	string id
        	string name
        	string record
          }
          Record||--|{ Field : contains
	  Field {
        	string id
        	string type
        	string format
        	string unit
        	string name
        	string description
        	string shortDisplayName
        	string internalNote
          }
          Field ||..o{ KPI : "uses"
```

You can then query Celonis knowledge and retrieve data either from a specific record or from any records and KPIs of the Knowledge Model.

- To query at the KM record level, the consumer selects:
  - the `fields` to be included in the results (`fields` can be raw or calculated *attributes*, *augmented attributes* or *flags*)
  - the predefined `filters` to be applied
  - the sorting field (`sort`)
  - ad-hoc filters to be applied (`filterExpr`)
  - the `pageSize` of the results and the current `page` index
- To query at the KM level, the consumer selects:
  - the `record.fields` to be included in the results
  - the `kpis` to be included in the results
  - the predefined `filters` to be applied
  - the sorting field (`sort`)
  - ad-hoc filters to be applied (`filterExpr`)
  - the `pageSize` of the results and the current `page` index


## Further Considerations

* In order to have access to a specific Knowledge Model and its contents, the Knowledge Model must be published in the Celonis Platform.
* The returned data corresponds to the last **published** version of the Knowledge Model.


## Feedback

We value your feedback and are constantly striving to improve our APIs.

If you have encountered any problems or have any suggestions for new features, please take a moment to share your
thoughts with us through
this [form](https://docs.google.com/forms/d/e/1FAIpQLSeHANiDNRaHNCbdgH0hc1kQv35V2yHb5gkDpZTYjoT-6Gd-rQ/viewform?usp=sf_link).

Your input is important to us and will help us make our APIs even better.