> For the complete documentation index, see [llms.txt](https://docs.kemperconnect.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kemperconnect.de/reference/api-reference.md).

# API Reference

## Overview

KEMPER Connect exposes a programmatic API that lets you integrate your existing IT/OT infrastructure with the KEMPER Connect Bridge and all connected KEMPER devices.

{% hint style="warning" %}
This is advanced topic. Please contact KEMPER Connect support for help on this topic.
{% endhint %}

### Is there a public or partner API?

Yes. KEMPER Connect offers several integration options, ranging from a ready-to-use **GraphQL API** to advanced real-time streaming and webhook integrations. The GraphQL API is available today; the advanced real-time options are optional, paid add-ons that KEMPER enables for you together with Datacake (see Integration Options).

The GraphQL API is a single endpoint. KEMPER Connect does **not** publish a separate REST API; all standard data access and device control is performed through GraphQL.

### Integration options at a glance

| Option                         | What it does                                                                 | Availability           |
| ------------------------------ | ---------------------------------------------------------------------------- | ---------------------- |
| GraphQL API                    | Read sites, devices, live telemetry and history; send commands; manage rules | Available now          |
| MQTT real-time live stream     | Continuous real-time push of measurement data to an MQTT broker              | Advanced add-on (paid) |
| Outgoing webhooks              | Immediate HTTPS push of measurement data to your endpoint                    | Advanced add-on (paid) |
| Rule-based webhooks / alerting | Trigger and control third-party systems from rules and alerts                | Advanced add-on (paid) |

See Integration Options for details on each option and how to request it.

### What the GraphQL API provides

| Capability                                           | Supported                                 |
| ---------------------------------------------------- | ----------------------------------------- |
| Read sites (workspaces) and their devices            | Yes                                       |
| Read live telemetry (current measurements)           | Yes                                       |
| Read historical time-series data                     | Yes                                       |
| Send remote commands (start/stop, parameter changes) | Yes (device-dependent)                    |
| Manage automation and scheduling rules               | Yes                                       |
| Email notifications on thresholds                    | Yes (via rules)                           |
| Real-time push (MQTT / webhooks)                     | Advanced add-on — see Integration Options |

### How to get access

Access to the GraphQL API is granted through a Datacake API token. 

{% hint style="danger" %}
Tokens **cannot** currently be self-generated in the KEMPER Connect portal. KEMPER provisions them for you as a custom setup step (see Authentication). To request API access, a dedicated API user, adapter scripts, or any of the advanced integration options, contact KEMPER.
{% endhint %}

***

## Integration Options

KEMPER Connect can expose device data and control through several channels. The GraphQL API is available immediately; the real-time and webhook options are advanced, paid add-ons enabled per customer.

### GraphQL API

A standard GraphQL endpoint for reading sites, devices, live telemetry and history, sending commands, and managing rules. This is the interface documented throughout the rest of this guide. It is best suited to request/response access and scheduled polling by middleware, historians, or BI tools.

### MQTT real-time live stream (advanced)

A continuous, real-time stream of measurement data to an MQTT broker. Instead of polling, your systems subscribe to topics and receive values as they arrive. Suited to live dashboards, SCADA/OT historians, and low-latency processing.

### Outgoing webhooks (advanced)

Measurement data is pushed to an HTTPS endpoint you provide, in real time as it is received. Suited to event-driven pipelines that ingest data without polling.

### Rule-based webhooks and alerting (advanced)

Webhooks fired from rules and alerts to actively drive third-party systems (for example, ticketing, alerting, or automation platforms) when a threshold or condition is met.

### Availability and how to request

* The **GraphQL API** can be enabled for your workspace today. KEMPER provisions your access token and, where available, adapter scripts to help you get started.
* The **MQTT live stream**, **outgoing webhooks**, and **rule-based webhooks** are **advanced topics** offered as a **paid API package**.
* These advanced options are delivered together with Datacake: contact KEMPER, we forward your request to Datacake, and Datacake sets up the integration and gets in touch with you directly.

To start, contact KEMPER with your use case and the systems you want to integrate.

***

## Authentication

The API uses **token-based authentication** (API key style). There is no OAuth2 authorization-code flow and no separate client-id/client-secret handshake. Every request carries a static token in the `Authorization` header.

### Token types

| Token type          | How it is obtained                         | Recommended for                 |
| ------------------- | ------------------------------------------ | ------------------------------- |
| Personal user token | Returned when a user account authenticates | Quick tests, single-user access |
| API user token      | Provisioned by KEMPER for a workspace      | Production/system integrations  |

For system-to-system integrations (SCADA, MES, PLC gateways, BI tools) we strongly recommend a **dedicated API user token**. It is not tied to a person, can be scoped to specific workspaces, and can be revoked independently.

> Important: API tokens cannot currently be created or managed self-service in the KEMPER Connect portal. KEMPER provisions them for you as a custom setup step, and can provide adapter scripts where available. Contact KEMPER to have your token (and, if needed, a dedicated API user) created.

### Header format

All requests must include the token using the `Token` scheme (not `Bearer`):

```http
Authorization: Token <YOUR_API_TOKEN>
Content-Type: application/json
```

> Note: The token is a Datacake DRF API key. It must be sent with the `Token` prefix. Sending it as `Bearer` will fail.

### Obtaining a token

#### API user token (recommended)

Contact KEMPER to have a dedicated API user created for your workspace. You will receive a long-lived token that you store securely in your integration (for example, in a secrets manager or environment variable).

### Security

* Always use HTTPS. All API traffic must be encrypted in transit.
* Treat the token like a password. Do not embed it in client-side code or commit it to source control.
* A request with a missing, invalid, or revoked token returns HTTP `401 Unauthorized`.

***

## Connecting to the API

### Endpoint

```
POST https://api.datacake.co/graphql/
```

All operations (queries and mutations) are sent as HTTP `POST` requests to this single endpoint.

### Request format

The request body is JSON with a `query` string and an optional `variables` object:

```json
{
  "query": "query { ... }",
  "variables": { "key": "value" }
}
```

### Minimal example

```bash
curl -X POST https://api.datacake.co/graphql/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { user { id email } }"}'
```

### Schema and introspection

The API is a standard GraphQL service and supports GraphQL introspection. You can point any GraphQL client (for example, Insomnia, Altair, or a code-generation tool) at the endpoint to browse the full schema, available types, and fields.

***

## Data Model

This section describes the core objects you will work with.

### Entity overview

```mermaid
flowchart TB
  User[User / API User]
  Workspace["Site (Workspace)"]
  Device[Device]
  Product[Product Type]
  Measurement[Measurement Field]
  Rule[Automation Rule]

  User --> Workspace
  Workspace --> Device
  Device --> Product
  Device --> Measurement
  Workspace --> Rule
  Rule --> Device
```

### Sites (Workspaces)

A **Site** in the KEMPER Connect UI corresponds to a Datacake **workspace**. It is the top-level container that groups devices and members. Every site is identified by a UUID.

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `id`          | UUID   | Unique site identifier (used as `siteId` in the app) |
| `name`        | String | Display name of the site                             |
| `slug`        | String | URL-friendly identifier                              |
| `deviceCount` | Int    | Number of devices in the site                        |
| `memberCount` | Int    | Number of members                                    |

### Devices

A **Device** is a physical KEMPER unit or sensor connected to a site.

| Field                 | Type           | Description                               |
| --------------------- | -------------- | ----------------------------------------- |
| `id`                  | UUID           | Unique device identifier                  |
| `verboseName`         | String         | Human-readable device name                |
| `serialNumber`        | String         | Device serial number                      |
| `claimSerialNumber`   | String         | Serial used to claim the device           |
| `product`             | Object         | Product type: `{ id, slug, hardware }`    |
| `online`              | Boolean        | Whether the device is currently connected |
| `lastHeard`           | DateTime       | Timestamp of last data transmission       |
| `tags`                | \[String]      | Free-form tags                            |
| `currentMeasurements` | \[Measurement] | Latest values (see Telemetry)             |

### Products

Each device has a `product` with a `slug` that identifies its type (for example, `airwatch-lte-europe`, `airdome`, `kemper-connect-bridge`). Product slugs determine which measurement fields and remote commands are available. See Device Types and Their Fields.

### Sensors and actuators

Devices fall into two functional roles for integration purposes:

* **Sensors** measure the environment. The primary air-quality sensor family is **AirWatch** (PM2.5 / PM10 particulate matter).
* **Actuators** are filtration units that can be controlled (AirDome, Clean Air Tower, and Bridge-connected filters).

### The KEMPER Connect Bridge

The **KEMPER Connect Bridge** (`product.slug = "kemper-connect-bridge"`) brings existing KEMPER machines online. A single bridge represents one downstream machine. The connected machine type is reported through the numeric `DEVICE_TYPE` measurement:

| `DEVICE_TYPE` range | Connected machine               |
| ------------------- | ------------------------------- |
| 1–19                | VacuFil Compact                 |
| 20–29               | MaxiFil Clean                   |
| 30–59               | Automation Line                 |
| 60–69               | AirDome                         |
| 70–79               | Clean Air Tower (self-cleaning) |

When controlling a Bridge device, commands are sent to the **bridge device ID** (not a separate downstream ID). See Remote Control.

***

## Sites and Devices

### List all sites

Returns every workspace (site) the token has access to.

```graphql
query GetSites {
  allWorkspaces {
    id
    name
    deviceCount
    memberCount
  }
}
```

### Get a single site

```graphql
query GetSite($workspaceId: String!) {
  workspace(id: $workspaceId) {
    id
    name
    slug
  }
}
```

### List devices in a site

```graphql
query GetDevices($workspaceId: String!) {
  allDevices(inWorkspace: $workspaceId) {
    id
    verboseName
    serialNumber
    product {
      id
      slug
      hardware
    }
    online
    lastHeard
    tags
  }
}
```

### Get a single device

```graphql
query GetDevice($deviceId: String!) {
  device(deviceId: $deviceId) {
    id
    verboseName
    serialNumber
    online
    lastHeard
    product {
      slug
    }
  }
}
```

***

## Telemetry and Operating Data

Telemetry is exposed through two mechanisms on a device: **current measurements** (latest value per field) and **history** (time-series).

### Current measurements

Request the latest value of one or more measurement fields by name. Field names are case-sensitive and vary by product (see Device Types and Their Fields).

```graphql
query GetCurrent($deviceId: String!) {
  device(deviceId: $deviceId) {
    currentMeasurements(
      fieldNames: ["PM10_VALUE", "PM25_VALUE", "MOTOR_RUNNING", "FAULT_CODE"]
    ) {
      value
      field {
        fieldName
      }
    }
  }
}
```

### Historical data

Historical values are returned as a JSON-encoded string for the requested fields, time range, and resolution.

```graphql
query GetHistory(
  $deviceId: String!
  $start: String!
  $end: String!
  $fields: [String]
  $resolution: Int
) {
  device(deviceId: $deviceId) {
    history(
      fields: $fields
      timerangestart: $start
      timerangeend: $end
      resolution: $resolution
    )
  }
}
```

### Data categories and field names

The tables below map the common operating data the customer asked about to the underlying field names. Some products use different casing or German field names; both variants are listed.

#### Status and connectivity

| Data          | Field(s)                  | Notes                        |
| ------------- | ------------------------- | ---------------------------- |
| Online status | `online`                  | Device attribute (boolean)   |
| Last seen     | `lastHeard`               | Device attribute (timestamp) |
| On/off        | `ON_OFF`, `MOTOR_RUNNING` | Boolean operational state    |

#### Air quality (particulate matter)

| Data            | Field(s)                                  | Unit     |
| --------------- | ----------------------------------------- | -------- |
| PM2.5           | `PM25_VALUE` / `pm25_value`               | µg/m³    |
| PM10            | `PM10_VALUE` / `pm10_value`               | µg/m³    |
| Total particles | `NR_PARTICLES` / `binSum`                 | count/m³ |
| Particle bins   | `BIN0_VALUE`–`BIN5_VALUE` / `bin0`–`bin5` | count    |

#### Alarms, faults and warnings

| Data       | Field(s)                              | Notes          |
| ---------- | ------------------------------------- | -------------- |
| Error code | `FEHLERCODE`                          | 0 = OK         |
| Fault code | `FAULT_CODE` / `fault_code` / `FAULT` | 0 = OK         |
| Warning    | `WARNING`                             | Warning status |

#### Runtime and maintenance

| Data                   | Field(s)                                            | Unit  |
| ---------------------- | --------------------------------------------------- | ----- |
| Operating hours        | `OPERATING_HOURS` / `BETRIEBSSTUNDEN`               | h     |
| Hours until service    | `MAINTENANCE_HOURS` / `BETRIEBSSTUNDEN_BIS_WARTUNG` | h     |
| Filter cleaning cycles | `NR_FILTER_CLEANINGS` / `ANZAHL_ABREINIGUNGEN`      | count |

#### Filter condition

| Data                  | Field(s)                                                        | Unit |
| --------------------- | --------------------------------------------------------------- | ---- |
| Filter pressure       | `PRESSURE_FILTER` / `FILTER_PRESSURE`                           | Pa   |
| Differential pressure | `DIFFERENTIAL_PRESSURE_FILTER` / `Differential_pressure_filter` | Pa   |

#### Motor and air flow

| Data              | Field(s)                                            | Unit |
| ----------------- | --------------------------------------------------- | ---- |
| Volume flow       | `VOLUMEFLOW` / `ACTUAL_VOLUMEFLOW` / `VOLUMENSTROM` | m³/h |
| Motor power       | `MOTORPOWER` / `MOTOR_ACTUAL_POWER`                 | kW   |
| Motor current     | `MOTORCURRENT` / `MOTOR_CURRENT`                    | A    |
| Motor temperature | `TEMPERATURE_MOTOR` / `MOTOR_TEMPERATURE`           | °C   |
| Motor frequency   | `MOTOR_FREQUENCY`                                   | Hz   |

#### Energy

| Data               | Field(s)             | Unit |
| ------------------ | -------------------- | ---- |
| Energy consumption | `ENERGY_CONSUMPTION` | kWh  |

#### Noise

| Data                             | Field(s)       | Unit |
| -------------------------------- | -------------- | ---- |
| Loudness (A-weighted equivalent) | `LAEQ`         | dB   |
| Instantaneous / max level        | `LA` / `LAMAX` | dB   |

***

## Device Types and Their Fields

Each product exposes its own set of measurement fields. Use the device's `product.slug` to determine which fields to query. This section lists the fields available per product.

### AirWatch (air quality sensor)

Variants: `airwatch-30`, `airwatch-lte-europe`, `kemper-airwatch-lte-america`.

| Purpose              | AirWatch LTE (Europe/America) | AirWatch 3.0             |
| -------------------- | ----------------------------- | ------------------------ |
| PM2.5                | `PM25_VALUE`                  | `pm25_value`             |
| PM10                 | `PM10_VALUE`                  | `pm10_value`             |
| Particle bins        | `BIN0_VALUE`–`BIN5_VALUE`     | `bin0`–`bin5`            |
| Total particles      | `NR_PARTICLES`                | `binSum`                 |
| PM10 alert threshold | `PM10_LIMIT_SET_VALUE`        | `settings_pm10grenzwert` |
| LED brightness       | `LED_BRIGHTNESS_SET_VAL`      | `settings_brightness`    |
| Signal strength      | `SIGNAL_STRENGTH`             | —                        |

### AirDome (air filtration tower)

`MOTOR_RUNNING`, `MOTORCURRENT`, `MOTORPOWER`, `VOLUMEFLOW`, `MOTOR_RPM_AVG`, `PRESSURE_VOLUMEFLOW`, `PRESSURE_FILTER`, `TOTAL_PRESSURE`, `WARNING`, `MAINTENANCE_HOURS`, `OPERATING_HOURS`, `NR_FILTER_CLEANINGS`, `FEHLERCODE`, `TARGET_RPM`.

### Clean Air Tower (self-cleaning)

`BETRIEBSSTUNDEN`, `BETRIEBSSTUNDEN_BIS_WARTUNG`, `ANZAHL_ABREINIGUNGEN`, `VOLUMENSTROM`, `ON_OFF`, `FEHLERCODE`, `SOFTWARESTAND`.

### Clean Air Tower (disposable filter)

`BETRIEBSSTUNDEN`, `BETRIEBSSTUNDEN_BIS_WARTUNG`, `ACTUAL_VOLUMEFLOW`, `PRESSURE_VOLUME_FLOW`, `MOTOR_RUNNING`, `FAULT_CODE`, `TEMPERATURE_MOTOR`, `MOTOR_CURRENT`, `MOTOR_ACTUAL_POWER`, `MOTOR_FREQUENCY`, `BOOST_MODE_ACTIVE`, `DIFFERENTIAL_PRESSURE_FILTER`.

### VacuFil 125

`Betriebsstunden`, `Betriebsstunden_bis_wartung`, `cloud_signal_rssi`, `Anzahl_Abreinigungen`, `Differential_pressure_filter`, `actual_volumeflow`, `state_latest`, `fault_code`.

### Bridge-connected filters

Reported through the KEMPER Connect Bridge (`DEVICE_TYPE` resolves the machine type).

* **VacuFil Compact:** `MOTOR_RUNNING`, `FAULT`, `WARNING`, `FILTER_CLEANINGS`, `MAINTENANCE_HOURS`, `OPERATING_HOURS`, `SOFTWARE_VERSION`, `MOTOR_TEMPERATURE`, `VOLUMEFLOW_PRESSURE`.
* **MaxiFil Clean:** `MOTOR_RUNNING`, `FAULT`, `WARNING`, `FILTER_PRESSURE`, `MAINTENANCE_HOURS`, `OPERATING_HOURS`, `NR_FILTERS_INSTALLED`, `VOLUMEFLOW_PRESSURE`.
* **Automation Line:** `MOTOR_RUNNING`, `MOTOR_TEMPERATURE`, `FAULT`, `WARNING`, `FILTER_CLEANINGS`, `NR_FILTERS_INSTALLED`, `VOLUMEFLOW_PRESSURE`, `FILTER_PRESSURE_LIMIT`.

### KemJet / WeldFil / System 9000

Identified by `product.hardware = "dzero"`. Generic I/O pins with fixed wiring semantics: analog `AI_0` (filter pressure, Pa); temperatures `TC_0`–`TC_2` (motor/filter/room, °C); digital inputs `IN1_0`–`IN1_3` (contactor feedback, motor protection, external on/off, phase monitoring).

### Noise sensor (Milesight WS302)

`LAEQ`, `LA`, `LAMAX`, `BATTERY`, `SIGNAL`.

### Energy meters

Any device reporting `ENERGY_CONSUMPTION` (kWh).

***

## Remote Control

The API supports remote control of filtration devices: start/stop, and (for some products) parameter changes. Commands are issued as GraphQL mutations. The mutation to use depends on the product.

### Control mutations by product

| Product                       | Mutation               | Purpose                                         |
| ----------------------------- | ---------------------- | ----------------------------------------------- |
| KEMPER Connect Bridge         | `sendApiDownlink`      | Start/stop the bridged machine                  |
| AirDome, AirWatch LTE         | `sendParticleDownlink` | Downlink command                                |
| Clean Air Tower, AirWatch 3.0 | `callProductFunction`  | Predefined function (e.g. start/stop, identify) |
| AirWatch LTE                  | `setValue`             | Change a settable parameter                     |
| AirWatch 3.0                  | `sendAw3CommandFrame`  | Change brightness / PM10 threshold              |

### Start / stop

Start and stop are performed by sending the product's corresponding downlink or function. For example, to start or stop a Bridge-connected machine:

```graphql
mutation SendBridgeCommand($device: String!, $downlink: String!) {
  sendApiDownlink(device: $device, downlink: $downlink) {
    ok
  }
}
```

For AirDome and Clean Air Tower devices, use the product's start/stop downlink/function identifiers. Contact KEMPER for the current downlink identifiers for your product, or read them from the device's function catalog exposed in the app.

### Parameter changes

AirWatch LTE devices support setting parameters such as the PM10 alert threshold and LED brightness:

```graphql
mutation SetValue(
  $deviceId: String!
  $fieldName: String!
  $value: MeasurementValueInput!
) {
  setValue(deviceId: $deviceId, fieldName: $fieldName, value: $value) {
    ok
    error {
      code
      details
    }
  }
}
```

### Which products support control?

| Product                         | Start/Stop |           Parameter changes          |
| ------------------------------- | :--------: | :----------------------------------: |
| AirDome                         |     Yes    |                   —                  |
| Clean Air Tower (self-cleaning) |     Yes    |                   —                  |
| Clean Air Tower (disposable)    |     Yes    |                   —                  |
| KEMPER Connect Bridge           |     Yes    |                   —                  |
| AirWatch LTE (Europe/America)   |      —     | Yes (`PM10_LIMIT`, `LED_BRIGHTNESS`) |
| AirWatch 3.0                    |      —     |   Yes (brightness, PM10 threshold)   |
| Bridge-connected filters        | Via Bridge |                   —                  |
| AirWatch (sensor readings)      |      —     |                   —                  |

> Automation-driven control (for example, turning filters on when PM10 exceeds a threshold) is best implemented with rules rather than direct commands. See Automation and Rules.

***

## Automation and Rules

KEMPER Connect includes a rules engine (Datacake **RuleNG**) that runs server-side. Rules can be read and managed through the API. Three rule patterns are used by KEMPER Connect:

### Time-based schedules

Turn devices on or off on a cron schedule (for example, ventilation during shift hours).

### PM-threshold automation

Automatically start a filtration device when a paired AirWatch sensor reports PM10 above a threshold, and stop it when it falls back below. Implemented as paired start/stop rules keyed on the sensor's PM10 field.

### Email notifications

Send an email to configured recipients when PM10 exceeds a threshold (with hysteresis to avoid flapping).

### Reading and managing rules

Rules belong to a workspace and are available through `rulesNG`:

```graphql
query GetRules($workspaceId: String!) {
  workspace(id: $workspaceId) {
    rulesNG {
      id
      name
      enabled
      triggerOnSchedule
      scheduleTriggerCrontab
    }
  }
}
```

Rules are created, updated, and deleted with the `createRuleNG`, `updateRuleNG`, and `deleteRuleNG` mutations.

***

## Events and Notifications

### Webhooks and real-time push

Real-time push integrations are available as **advanced, paid add-ons** rather than through the standard GraphQL API:

* **Outgoing webhooks** — measurement data pushed to your HTTPS endpoint as it arrives.
* **MQTT live stream** — continuous real-time data via an MQTT broker.
* **Rule-based webhooks** — webhooks fired from rules and alerts to drive third-party systems.

These are enabled per customer together with Datacake. See Integration Options and contact KEMPER to request them. If you are using only the standard GraphQL API, use polling (below) to detect events.

### Email notifications

The only built-in outbound notification channel is **email**, configured through threshold rules (see Automation and Rules). Emails can include templated device data such as the triggering device name and its current PM10 value.

### Detecting events by polling

For system integrations that need to react to state changes (alarms, faults, threshold crossings, on/off transitions), poll the relevant `currentMeasurements` or `history` on a schedule and detect changes in your own system. Recommended polling intervals:

| Data type                     | Suggested interval |
| ----------------------------- | ------------------ |
| Air quality / live telemetry  | 1–5 minutes        |
| Status / faults               | 1–5 minutes        |
| Operating hours / maintenance | Hourly or daily    |
| Historical backfill           | On demand          |

Avoid polling faster than the device's own reporting interval; most devices report at a fixed cadence, so more frequent polling returns unchanged values.

***

## Example Requests and Responses

### Is there a Postman collection?

There is no official Postman collection today. Because the API is standard GraphQL, you can import the schema into any GraphQL client via introspection (see Schema and introspection). The copy-paste examples below cover the most common tasks.

### List devices in a site

Request:

```bash
curl -X POST https://api.datacake.co/graphql/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($ws:String!){ allDevices(inWorkspace:$ws){ id verboseName online product{ slug } } }",
    "variables": { "ws": "YOUR_WORKSPACE_ID" }
  }'
```

Response:

```json
{
  "data": {
    "allDevices": [
      {
        "id": "0a1b2c3d-1111-2222-3333-444455556666",
        "verboseName": "AirWatch Hall 1",
        "online": true,
        "product": { "slug": "airwatch-lte-europe" }
      }
    ]
  }
}
```

### Read current air quality

Request:

```bash
curl -X POST https://api.datacake.co/graphql/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ device(deviceId:$id){ currentMeasurements(fieldNames:[\"PM10_VALUE\",\"PM25_VALUE\"]){ value field{ fieldName } } } }",
    "variables": { "id": "YOUR_DEVICE_ID" }
  }'
```

Response:

```json
{
  "data": {
    "device": {
      "currentMeasurements": [
        { "value": 42.5, "field": { "fieldName": "PM10_VALUE" } },
        { "value": 18.0, "field": { "fieldName": "PM25_VALUE" } }
      ]
    }
  }
}
```

### Send a start command to a Bridge device

Request:

```bash
curl -X POST https://api.datacake.co/graphql/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($d:String!,$dl:String!){ sendApiDownlink(device:$d, downlink:$dl){ ok } }",
    "variables": { "d": "YOUR_BRIDGE_DEVICE_ID", "dl": "START_DOWNLINK_ID" }
  }'
```

Response:

```json
{
  "data": {
    "sendApiDownlink": { "ok": true }
  }
}
```

***

## Integrating with Third-Party Systems

The GraphQL API is designed to be consumed by middleware and enterprise platforms. Below are integration patterns for common systems.

### SCADA, MES and PLC

These systems typically cannot call GraphQL directly. Use a small **integration gateway** (a script or service) that:

1. Authenticates once with an API user token.
2. Polls `currentMeasurements` / `history` on a fixed cadence.
3. Maps KEMPER field names to your process tags.
4. Writes values into your SCADA/MES historian or PLC data table (for example via OPC UA, Modbus, or a REST bridge you control).

For control, the gateway issues the relevant GraphQL mutation (start/stop, parameter change) in response to your system's commands.

```mermaid
flowchart LR
  KConnect["KEMPER Connect GraphQL API"]
  Gateway["Integration Gateway (your side)"]
  OT["SCADA / MES / PLC"]

  KConnect -->|"poll telemetry"| Gateway
  Gateway -->|"process tags (OPC UA / Modbus)"| OT
  OT -->|"commands"| Gateway
  Gateway -->|"mutations"| KConnect
```

### Power BI and BI tools

Use a scheduled pull of the data you need:

* **Power BI:** Use the *Web* connector (`Web.Contents`) to POST the GraphQL query with the `Authorization: Token` header, then parse the JSON response into a table. Configure scheduled refresh for periodic updates. For historical trending, query `history` over the desired range.
* **Other BI tools:** Any tool that can perform an authenticated HTTP POST and parse JSON can consume the API. Prefer querying aggregated/history data on a schedule over high-frequency polling.

### General recommendations

* Use a dedicated **API user token** per integration so it can be rotated or revoked independently.
* Cache results and respect device reporting cadence; do not poll faster than the data changes.
* Batch multiple devices/fields into a single query where possible to reduce request volume.
* Build change detection (alarms, thresholds) in your own layer when using the GraphQL API, or request the outgoing webhook / MQTT add-ons for real-time push (see Integration Options).

***

## Limitations and Support

### Current limitations

* **Standard interface is GraphQL**, there is and will be **NO separate REST API**. Real-time push (MQTT, outgoing webhooks, rule-based webhooks) is available as a paid add-on; see Integration Options.
* **Tokens are provisioned by KEMPER.** API tokens cannot be created self-service in the portal.
* **Control availability varies by product and security,** see Remote Control.
* **Field names vary by product,** always resolve fields from the device `product.slug`.

### Support and access requests

* To request a dedicated **API user** or **partner API** access, contact KEMPER.
* To request advanced real-time integrations (MQTT live stream, outgoing webhooks, rule-based webhooks), contact KEMPER; these are offered as a paid API package set up together with Datacake.
* Adapter scripts and integration starter code may be available on request.
* For product-specific downlink identifiers used in control mutations, contact KEMPER or inspect the device's function catalog in the KEMPER Connect app.
* Keep your API token secure and rotate it if you suspect exposure.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kemperconnect.de/reference/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.