Kärcher External IoT API (1.0.0)

Before you can use the Kärcher External IoT API, you need to authenticate your requests. This section explains how to get access and use the API securely.

What You Need to Get Started

1. Client ID: A unique identifier for your application (provided by Kärcher)
2. Client Secret: A secure password for your application (provided by Kärcher)
3. Environment: Choose between Production or Staging environment

Note: If you don't have these credentials yet, please contact your Kärcher representative to request API access.

How Authentication Works

The API uses a secure authentication method called OAuth 2.0. Here's the simple process:

1. Get a Token: Use your credentials to get a temporary access token
2. Use the Token: Include this token in all your API requests
3. Token Expires: Tokens expire after 1 hour, so you'll need to get a new one

Step 1: Getting Your Access Token

First, you need to get an access token using your credentials.

Choose your environment:

• Production : https://auth.fds.kaercher.com/oauth2/token

• Staging : https://auth.stage.fds.kaercher.com/oauth2/token

• Access token rate limit: 10 requests/10 minutes

Make this request:

# Production Environment
curl -X POST https://auth.fds.kaercher.com/oauth2/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

You'll get back a response like this:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Important: Save the access_token value - you'll need it for the next step!

Step 2: Using Your Access Token

Now you can make API requests by including your token in the Authorization header.

Example API request:

curl -X GET https://api.fds.kaercher.com/external/v1/machines/specifications \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Common Problems and Solutions

The Kärcher External IoT API supports multiple device families, each with distinct characteristics, operational patterns, and capabilities. Understanding these family-specific differences is crucial for proper API integration.

Note: While this API is primarily focused on robotic devices, it is a general IoT API and also offers access to non-robotic devices. Capabilities and available data for non-robotic devices may differ significantly from those of robots, and only basic information may be available for some device types.

Device Family Overview

Each device family represents a group of machines with similar functionality and operational behavior. While all families use the same API endpoints (/machine/{materialNumber}/{serialNumber}/), they differ significantly in:

• Status states - Available machine states vary by family
• Command payloads - Each family has specific command structures
• Cleaning report formats - Report data and asset types differ
• Operational concepts - Mission vs. map-based operations

Supported Device Families

KIRA Scrubber Family

Autonomous floor cleaning robots with routine-based operation

Image	Material Number	Model	Description
	1.533-001.0	KIRA B50 HW 1.0	Midsize autonomous scrubber dryer with roller brushes
	1.533-002.0	KIRA B50 HW 2.0	Midsize autonomous scrubber dryer with roller brushes
	1.533-003.0	KIRA BR50 HW 3.0	Midsize autonomous scrubber dryer with roller brushes
	1.533-050.0	KIRA BD50	Midsize autonomous scrubber dryer with disc brushes
	1.533-013.0	KIRA BR200	Large autonomous scrubber dryer with roller brushes
	1.533-014.0	KIRA BD200	Large autonomous scrubber dryer with disc brushes

Key Characteristics:

• Routine and single mission-based operation
• SVG-based cleaning report assets
• Advanced navigation and mapping capabilities

KIRA Vacuum Family

Compact commercial vacuum cleaners with map-level operation

Image	Material Number	Model	Description
	1.454-500.0	CV50	Professional dry vacuum
	1.454-505.0	CV50 USA	Professional dry vacuum

Key Characteristics:

• Map-level operation focus
• PNG-based cleaning report assets
• Manual and semi-automated operation modes

KIRA Family States

KIRA Vacuum Family States

Our cloud interfaces with cleaning devices by issuing specific commands. We currently support two primary device classes: Kira and CV50. Each class has a distinct set of commands and payload structures.

This section defines the specific command names, arguments, and behaviors available for the Kira device class.

Mission Commands

Available since version 2.3.0.

These are argument-free commands used to control the execution state of the currently active mission or repeat.

• missionPause: Pauses the currently active mission/repeat. This is the equivalent of the Pause button on the Kira's HMI. The mission can be resumed using the missionResume command.

• missionResume: Resumes a currently paused mission/repeat. This is the equivalent of the Resume button on the Kira's HMI.

• missionStop: Instantly cancels the active mission/repeat. The Kira will remain at its current position. Note: Starting a new mission/repeat at this location will likely fail, as the Kira requires a docking station or landmark to localize itself for every mission. This is the equivalent of the Cancel button on the Kira's HMI.

• missionDriveBackAndSkip: Skips the current route in a routine after driving back to the docking station or landmark. This is the equivalent of the Skip button on the Kira's HMI.

• missionInstinctiveDocking: Interrupts the current route and drives the Kira back to the docking station to exchange resources. Afterward, the Kira will return to the position where it was interrupted and continue the route.

• missionDriveBackAndCancel: Cancels the current route/routine after driving back to the docking station or landmark. This is the recommended method for canceling a mission (preferred over missionStop), as it ensures the Kira is positioned to start new missions at a valid location.

Scheduling Commands

These are commands used to create, update or destroy schedules on the robot.

RRule — Recurrence Rules

All scheduling commands use an rrule string to define when a schedule runs. RRule is a standard format for expressing recurring calendar dates. The Kira device supports a specific subset of the full RRule specification, described below.

An rrule string is composed of two or three newline-separated (\n) components:

1. DTSTART — defines the start date and time with timezone
2. RRULE — defines the recurrence pattern
3. EXDATE (optional) — excludes specific dates from the series

Example structure:

DTSTART;TZID=Europe/Berlin:20250826T114100\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=1\nEXDATE;TZID=Europe/Berlin:20250821T113100

Supported fields:

Examples:

// A single, one-time schedule on the given DTSTART time
DTSTART;TZID=Europe/Berlin:20250428T161100\nRRULE:FREQ=DAILY;COUNT=1;INTERVAL=1

// A weekly repeating schedule on Mondays, Thursdays, and Sundays until 2025-09-01
DTSTART;TZID=Europe/Berlin:20250831T090800\nRRULE:FREQ=WEEKLY;UNTIL=20250901T235900;INTERVAL=1;BYDAY=MO,TH,SU

// A daily repeating schedule with 2025-08-21 excluded
DTSTART;TZID=Europe/Berlin:20250801T113100\nRRULE:FREQ=DAILY;UNTIL=20250822T235900;INTERVAL=1\nEXDATE;TZID=Europe/Berlin:20250821T113100

scheduleAdd

Registers a new rrule-based schedule directly on the Kira device. It supports scheduling single routes, standard routines, or on-the-fly anonymous routines.

Parameters

Examples

// Adding a schedule for an existing routine (ID: 57)
{
  "name": "a-routine-schedule",
  "color": "#b1b0a1",
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T114000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2",
  "routineId": 57,
}

// Adding a schedule for a single existing route (ID: 18)
{
  "name": "a-route-schedule",
  "color": "#4b8969",
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T114000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2",
  "routeIds": [18],
}

// Adding a schedule for a new anonymous routine (Routes: 18, 23, 18)
{
  "name": "a-new-routine-schedule",
  "color": "#238c96",
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T114000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2",
  "routeIds": [18, 23, 18],
}

Response

Upon successful completion, the newly created scheduleId is returned within the statusDetails object. You can use this ID to correlate the schedule with the new entry in the schedules telemetry. Additionally, the new schedule entry will include the jobId of this command.

Note: statusDetails only supports string values. Ensure you parse scheduleId to an integer when using it in subsequent API calls.

{
  "status": "SUCCEEDED",
  "statusDetails": {
    "scheduleId": "44"
  },
  "updatedAt": "2025-09-03T10:13:13.03Z"
}

scheduleChange

Modifies an existing schedule. All parameters except scheduleId are optional. Any omitted parameter will retain its current value.

Parameters

Examples

// Updating only name and color
{
  "scheduleId": 22,
  "name": "hustling-time",
  "color": "#6e6e6e",
}

// Updating the rrule time and routine assignment
{
  "scheduleId": 22,
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T124000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2",
  "routineId": 115,
}

// Excluding specific dates from an existing series
{
  "scheduleId": 22,
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T124000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2\nEXDATE;TZID=Europe/Berlin:20250814T163300,20250822T163300",
}

// Updating all properties in a single call
{
  "scheduleId": 22,
  "name": "hustling-time",
  "color": "#6e6e6e",
  "rrule": "DTSTART;TZID=Europe/Berlin:20250824T124000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=2\nEXDATE;TZID=Europe/Berlin:20250814T163300,20250822T163300",
  "routineId": 115,
}

scheduleNow

Instantly schedules and executes a defined routine or set of routes.

Parameters

scheduleRemove

Removes an existing schedule from the Kira device.

Parameters

This section shows a general end-to-end example of sending a command to a Kira machine, polling its status, and optionally cancelling or reviewing history. The example uses scheduleAdd to register a new daily cleaning schedule for an existing routine.

Step 1 — Send a Command

POST /machines/{materialNumber}/{serialNumber}/commands

curl -X POST https://api.fds.kaercher.com/external/v1/machines/1.533-002.0/000001/commands \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "commandName": "scheduleAdd",
    "commandParameters": {
      "name": "morning-clean",
      "color": "#4b8969",
      "rrule": "DTSTART;TZID=Europe/Berlin:20250826T070000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=1",
      "routineId": 57
    }
  }'

Response 200 OK:

{
  "commandName": "scheduleAdd",
  "commandParameters": {
    "name": "morning-clean",
    "color": "#4b8969",
    "rrule": "DTSTART;TZID=Europe/Berlin:20250826T070000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=1",
    "routineId": 57
  },
  "createdAt": "2025-06-11T11:51:51.077Z",
  "executionId": "36fxuYjGPr9QWCcjNgLg15"
}

Save the executionId from the response — you'll use it to track or cancel the execution.

Step 2 — Poll Execution Status

GET /machines/command-execution/{executionId}

curl -X GET https://api.fds.kaercher.com/external/v1/machines/command-execution/36fxuYjGPr9QWCcjNgLg15 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response 200 OK:

{
  "data": {
    "executionId": "36fxuYjGPr9QWCcjNgLg15",
    "commandName": "scheduleAdd",
    "commandParameters": {
      "name": "morning-clean",
      "rrule": "DTSTART;TZID=Europe/Berlin:20250826T070000\nRRULE:FREQ=DAILY;UNTIL=20250930T235900;INTERVAL=1",
      "color": "#4b8969",
      "routineId": 6
    },
    "executionRequester": "7sup7pd...",
    "createdAt": "2026-03-27T13:51:26.437Z",
    "executionEvents": [
      {
        "status": "SUCCEEDED",
        "updatedAt": "2026-03-27T13:54:38.635Z"
      },
      {
        "status": "QUEUED",
        "updatedAt": "2026-03-27T13:51:29.402Z"
      },
      {
        "status": "REQUESTED",
        "updatedAt": "2026-03-27T13:51:24.062Z"
      }
    ]
  }
}

Step 3 — (Optional) Cancel If Still Queued or In Progress

DELETE /machines/command-execution/{executionId}

A command can only be cancelled if it is in the QUEUED or IN_PROGRESS status.

curl -X DELETE https://api.fds.kaercher.com/external/v1/machines/command-execution/36fxuYjGPr9QWCcjNgLg15 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns 204 No Content on success.

Step 4 — (Optional) View Execution History

GET /machines/{materialNumber}/{serialNumber}/command-executions

curl -X GET "https://api.fds.kaercher.com/external/v1/machines/1.533-002.0/000001/command-executions?limit=10&sort=desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Notes:

• For argument-free commands such as missionPause, missionResume, and missionStop, use an empty commandParameters: {}.
• The scheduleAdd example above registers a daily routine (ID 57) running at 07:00 Berlin time from 2025-08-26 through 2025-09-30.
• Rate limit: 5 requests/second on command endpoints.

Unlike the Kira class, the CV50 device class operates using a single, unified top-level command called cv50_set. All specific actions, configurations, and operations are passed as sub-commands within the payload of this main command.

Wrapper Structure (cv50_set):

The payload for a cv50_set command must contain a keys array. Currently, this array is strictly limited to a single element. This single object within the array must contain exactly one key-value pair, where the key is the sub-command string (e.g., "settings.lights") and the value is its corresponding parameter object.

Payload Example:

{
  "keys": [
    {
      "settings.lights": {
        "status": 0.0
      }
    }
  ]
}

Below are the available sub-commands, their parameters, and the expected JSON structures for their parameter objects.

Cleaning Profiles (cleaningProfile.*)

Commands for managing maps, schedules, and cleaning profiles.

cleaningProfile.schedule.set

Creates or updates a cleaning schedule for a specific map.

Parameters

Parameter JSON Example:

{
  "weekDays": [0, 2],
  "startTime": "08:01",
  "repetition": 0,
  "mode": 1,
  "mapId": "82e79191-c216-43ea-a963-67b6d2a4b82e",
  "scheduleId": "7e0adfd5-e65a-488e-954d-70b05219b137"
}

cleaningProfile.schedule.delete

Deletes a specific schedule from a profile.

Parameters

Parameter JSON Example:

{
  "scheduleId": "7e0adfd5-e65a-488e-954d-70b05219b137",
  "mapId": "82e79191-c216-43ea-a963-67b6d2a4b82e"
}

cleaningProfile.delete

Deletes an entire map profile.

Parameters

Parameter JSON Example:

{
  "mapId": "82e79191-c216-43ea-a963-67b6d2a4b82e"
}

Device Settings (settings.*)

Commands for configuring the robot's hardware settings, security, and user interface.

Parameters & Examples

settings.hmiLanguage

Sets the interface language of the robot's HMI.

Parameters

Supported Codes:

de (German), fr (French), nl (Dutch), en (English), sv (Swedish), no (Norwegian), fi (Finnish), da (Danish), pl (Polish), cs (Czech), sk (Slovak), ja (Japanese), ko (Korean), es (Spanish), pt (Portuguese), it (Italian), el (Greek), tr (Turkish), ru (Russian), ar (Arabic), zh (Chinese), hr (Croatian), sl (Slovenian), sr (Serbian), uk (Ukrainian), ro (Romanian), hu (Hungarian), et (Estonian), bg (Bulgarian), lv (Latvian).

Parameter JSON Example:

{
  "hmiLanguage": "en"
}

Cleaning Operations (cleaning.*)

Real-time commands to control the robot's physical movement and cleaning state.

Remote Control (remote.*)

This section shows an end-to-end example of sending a cv50_set command to a CV50 machine. The example updates the robot's sound volume setting.

Step 1 — Send a Command

POST /machines/{materialNumber}/{serialNumber}/commands

curl -X POST https://api.fds.kaercher.com/external/v1/machines/1.454-500.0/000042/commands \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "commandName": "cv50_set",
    "commandParameters": {
      "keys": [
        {
          "settings.soundVolume": {
            "soundVolume": 75
          }
        }
      ]
    }
  }'

Response 200 OK:

{
  "commandName": "cv50_set",
  "commandParameters": {
    "keys": [
      {
        "settings.soundVolume": {
          "soundVolume": 75
        }
      }
    ]
  },
  "createdAt": "2025-06-11T12:00:00.000Z",
  "executionId": "7t8wChhKBuuD4ToGqPYYYS"
}

Step 2 — Poll Execution Status

GET /machines/command-execution/{executionId}

curl -X GET https://api.fds.kaercher.com/external/v1/machines/command-execution/7t8wChhKBuuD4ToGqPYYYS \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response 200 OK:

{
  "data": {
    "executionId": "7t8wChhKBuuD4ToGqPYYYS",
    "commandName": "cv50_set",
    "commandParameters": {
      "keys": [
        {
          "settings.soundVolume": {
            "soundVolume": 75
          }
        }
      ]
    },
    "executionRequester": "7sup7pd...",
    "createdAt": "2026-03-27T13:27:30.018Z",
    "executionEvents": [
      {
        "status": "SUCCEEDED",
        "updatedAt": "2026-03-27T13:41:40.336Z"
      },
      {
        "status": "QUEUED",
        "updatedAt": "2026-03-27T13:27:33.573Z"
      },
      {
        "status": "REQUESTED",
        "updatedAt": "2026-03-27T13:27:27.206Z"
      }
    ]
  }
}

Step 3 — (Optional) Cancel If Still Queued or In Progress

DELETE /machines/command-execution/{executionId}

A command can only be cancelled if it is in the QUEUED or IN_PROGRESS status.

curl -X DELETE https://api.fds.kaercher.com/external/v1/machines/command-execution/7t8wChhKBuuD4ToGqPYYYS \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns 204 No Content on success.

Note: The keys array must contain exactly one sub-command object per request. To apply multiple settings, send separate cv50_set commands.

The Kira device publishes structured telemetry data for its routes, routines, and schedules. These telemetry datapoints reflect the on-device state and are available via the machine status API.

Note on size limits: Due to the 128 kB IoT message size limit, each telemetry datapoint is capped at a maximum of 330 items. Any items that exceed this limit are published separately under the corresponding overflow key (e.g., routesOverflow, routinesOverflow, schedulesOverflow). A prioritization strategy is applied to ensure the most relevant items are always included within the limit — items that were recently created, modified, or executed take priority. The order of items in the array does not indicate this priority.

routes

Routes describe individual cleaning missions that were manually recorded during a TeachIn session.

Example item:

{
  "id": 44,
  "name": "4-long-loop-4",
  "startLandmark": "id_4",
  "endLandmark": "id_4",
  "createdAt": "2025-08-15T09:33:34.209849Z",
  "modifiedAt": "2025-05-30T13:37:05.099357Z",
  "thumbnailZipS3": "11989085954014531794.44_mission.zip",
  "mapZipS3": "14862309742929315492.44.zip",
  "duration": "00:15:00",
  "postChargingDuration": "00:15:00"
}

Fields:

routines

A routine is an ordered sequence of routes, where each successive route starts at the end landmark of the previous one.

Example item:

{
  "id": 74,
  "createdAt": "2025-08-15T09:33:34.209849Z",
  "modifiedAt": "2025-04-28T15:07:56.699435Z",
  "name": "trip",
  "routeIds": [24, 26, 30, 24],
  "anonymous": false,
  "duration": "00:15:00",
  "postChargingDuration": "00:15:00"
}

Fields:

Note: A routine is only valid if each pair of neighboring routes shares the same landmark — the endLandmark of one route must match the startLandmark of the next.

schedules

Schedules define when routines are executed, using an rrule string for recurrence (see RRule — Recurrence Rules above).

Example item:

{
  "id": 26,
  "name": "six",
  "createdAt": "2025-08-15T09:33:34.209849Z",
  "modifiedAt": "2025-04-28T15:07:56.699435Z",
  "idRoutine": 112,
  "rrule": "DTSTART;TZID=Europe/Berlin:20250925T114300\nRRULE:FREQ=DAILY;COUNT=1;INTERVAL=1",
  "color": "#b1b0a1",
  "idParentSchedule": null
}

Fields:

Note: Schedules can only reference routines. To schedule a single route, Kira automatically generates an anonymous routine containing that route.

idParentSchedule — Deviating Events

A single occurrence within a recurring schedule can deviate from the rest of the series. This is represented by two linked schedule entries:

• The parent schedule contains the recurring rrule, with an EXDATE entry that removes the specific occurrence from the normal series.
• The child schedule contains a one-time rrule for the deviating event and references the parent via idParentSchedule.

Example:

[
  {
    "id": 21,
    "name": "one",
    "createdAt": "2025-08-15T09:30:32.335724",
    "modifiedAt": "2025-08-15T09:30:32.335724",
    "idRoutine": 97,
    "rrule": "DTSTART;TZID=Europe/Berlin:20250819T114000\nRRULE:FREQ=DAILY;UNTIL=20250830T235900;INTERVAL=1\nEXDATE;TZID=Europe/Berlin:20250819T114000",
    "color": "#b1b0a1",
    "idParentSchedule": null
  },
  {
    "id": 29,
    "name": "one",
    "createdAt": "2025-08-19T09:38:59.870097",
    "modifiedAt": "2025-08-15T09:30:32.335724",
    "idRoutine": 97,
    "rrule": "DTSTART;TZID=Europe/Berlin:20250819T135500\nRRULE:FREQ=DAILY;COUNT=1;INTERVAL=1",
    "color": "#b1b0a1",
    "idParentSchedule": 21
  }
]

In this example, schedule 21 is a daily recurring series with the occurrence on 2025-08-19 excluded via EXDATE. Schedule 29 is a one-time replacement for that excluded occurrence, running at a different time and pointing back to its parent via idParentSchedule: 21.

For legal information and imprint, please visit: Kärcher Legal Information

The following endpoints are available for interacting with the Kärcher External IoT API: