ioBroker Simple-API Adapter

Zuletzt aktualisiert: 16. September 2026

Mit der ioBroker Simple API lassen sich Datenpunkte über einfache HTTP-Aufrufe auslesen und verändern. Damit können beispielsweise ESP32- und ESP8266-Projekte, Skripte, Apps oder andere Systeme auf ioBroker zugreifen, ohne einen eigenen ioBroker-Adapter entwickeln zu müssen.

Der Simple-API-Adapter existiert bereits seit vielen Jahren und funktioniert auch heute noch. Inzwischen gibt es allerdings einige Änderungen bei Konfiguration, Sicherheit und Authentifizierung. Außerdem steht mit dem REST-API-Adapter eine modernere Alternative zur Verfügung.

Was ist die ioBroker Simple API?

Die Simple API stellt eine HTTP-Schnittstelle für ioBroker bereit. Über bestimmte URLs können Zustände gelesen oder verändert werden.

Ein einfacher Aufruf kann zum Beispiel den aktuellen Wert eines Temperatursensors zurückgeben. Ein anderer Aufruf kann einen Datenpunkt auf true, false oder einen bestimmten Zahlenwert setzen.

Interessant ist das unter anderem für:

• ESP8266 und ESP32
• eigene Sensoren
• HTTP Shortcuts
• iOS Kurzbefehle
• kleine Webanwendungen
• Shell-Skripte
• externe Automatisierungen

Simple API oder REST API?

Für bestehende Installationen kann die Simple API weiterhin sinnvoll sein. Gerade sehr einfache HTTP-Aufrufe lassen sich damit schnell umsetzen.

Für ein neues Projekt würde ich inzwischen allerdings auch einen Blick auf den ioBroker REST-API-Adapter werfen. Dieser besitzt unter anderem eine Swagger-Oberfläche zum Ausprobieren der Schnittstelle und bietet zusätzliche Möglichkeiten.

Wenn du bereits bestehende URLs mit Simple API verwendest, gibt es aber keinen Grund, eine funktionierende Installation sofort umzubauen.

Simple-API-Adapter installieren

Öffne zunächst die ioBroker-Administrationsoberfläche und wechsle in den Bereich Adapter.

1. Nach Simple API suchen.
2. Adapter installieren.
3. Eine Instanz anlegen.
4. Konfiguration der Instanz öffnen.

Nach der Installation solltest du zunächst entscheiden, ob die Simple API einen eigenen Webserver verwenden oder als Erweiterung einer vorhandenen ioBroker-Webinstanz laufen soll.

Port 8087 und Web-Erweiterung

Bei einer klassischen Simple-API-Installation läuft die Schnittstelle häufig über den Port 8087.

Ein Beispiel im lokalen Netzwerk sieht dann so aus:

http://192.168.178.50:8087/

Seit neueren Adapter-Versionen kann Simple API auch als Erweiterung einer ioBroker-Webinstanz betrieben werden. In diesem Modus öffnet der Adapter keinen zusätzlichen eigenen Port. Welche Adresse du verwenden musst, hängt dann von der ausgewählten Webinstanz ab.

Wenn eine ältere Anleitung mit Port 8087 bei dir nicht funktioniert, solltest du deshalb zuerst die Konfiguration der Simple-API-Instanz prüfen.

Simple API testen

Eine praktische Funktion des Adapters ist die integrierte Hilfe. Wenn deine Instanz klassisch auf Port 8087 läuft, kannst du folgende Adresse im Browser öffnen:

http://192.168.178.50:8087/help

Ersetze die IP-Adresse durch die Adresse deines ioBroker-Servers. Die Hilfe zeigt dir die verfügbaren Befehle der installierten Adapter-Version.

ioBroker Datenpunkt einfach auslesen

Wenn nur der aktuelle Wert eines Datenpunkts benötigt wird, ist getPlainValue besonders praktisch.

Angenommen, wir möchten folgenden Datenpunkt auslesen:

0_userdata.0.Sensoren.Wohnzimmer.Temperatur

Der Aufruf sieht dann so aus:

http://192.168.178.50:8087/getPlainValue/0_userdata.0.Sensoren.Wohnzimmer.Temperatur

Als Antwort erhältst du nur den eigentlichen Wert, beispielsweise:

21.7

Kompletten Datenpunkt als JSON auslesen

Benötigst du neben dem Wert auch zusätzliche Informationen wie Zeitstempel oder Bestätigung, kannst du get verwenden.

http://192.168.178.50:8087/get/0_userdata.0.Sensoren.Wohnzimmer.Temperatur?prettyPrint

Die Antwort enthält dann unter anderem den eigentlichen Wert, Zeitstempel und weitere Informationen des States.

Der Parameter prettyPrint sorgt lediglich dafür, dass die JSON-Ausgabe im Browser besser lesbar dargestellt wird.

ioBroker Datenpunkt per HTTP setzen

Mit dem Befehl set lässt sich ein vorhandener Datenpunkt verändern.

Beispielsweise möchten wir den Datenpunkt

0_userdata.0.Test.Licht

auf true setzen:

http://192.168.178.50:8087/set/0_userdata.0.Test.Licht?value=true

Für einen Zahlenwert funktioniert das genauso:

http://192.168.178.50:8087/set/0_userdata.0.Test.Helligkeit?value=50

Der Datenpunkt muss bereits vorhanden sein. Außerdem sollte der übergebene Wert zum Datentyp des States passen.

Boolean-Datenpunkt mit Toggle umschalten

Für Schalter ist der Befehl toggle praktisch. Ein Boolean-Wert wird dabei jeweils umgekehrt.

Aus true wird false und umgekehrt:

http://192.168.178.50:8087/toggle/0_userdata.0.Test.Licht?prettyPrint

Damit lässt sich beispielsweise ein einfacher HTTP-Button bauen, der bei jedem Aufruf zwischen Ein und Aus wechselt.

Mehrere Datenpunkte mit setBulk schreiben

Wenn mehrere Werte gleichzeitig übertragen werden sollen, muss nicht für jeden Datenpunkt ein eigener HTTP-Aufruf durchgeführt werden.

Mit setBulk lassen sich mehrere Werte in einer Anfrage setzen:

http://192.168.178.50:8087/setBulk?0_userdata.0.Sensor.Temperatur=21.5&0_userdata.0.Sensor.Luftfeuchtigkeit=48&prettyPrint

Das ist beispielsweise interessant, wenn ein ESP32 mehrere Messwerte gleichzeitig an ioBroker übermitteln soll.

Mehrere Werte auslesen

Mit getBulk können mehrere States in einem Aufruf abgefragt werden.

http://192.168.178.50:8087/getBulk/0_userdata.0.Sensor.Temperatur,0_userdata.0.Sensor.Luftfeuchtigkeit/?prettyPrint

Die Antwort enthält die angeforderten Datenpunkte mit ihren aktuellen Werten und Zeitinformationen.

POST statt GET verwenden

Für einfache Tests ist ein GET-Aufruf im Browser bequem. Sobald größere Werte oder komplexere Integrationen gebaut werden, kann POST sinnvoller sein.

Simple API unterstützt unter anderem POST-Anfragen für setBulk und setValueFromBody. Bei diesen Aufrufen können Daten direkt im Request-Body übertragen werden.

Das ist besonders praktisch für Mikrocontroller, Skripte oder andere Systeme, die ohnehin HTTP-POST verwenden.

Authentifizierung der Simple API

Eine offene HTTP-Schnittstelle sollte nicht ungeschützt erreichbar sein. Neuere Versionen der Simple API unterstützen mehrere Möglichkeiten zur Authentifizierung.

• Benutzername und Passwort als Parameter
• HTTP Basic Authentication
• OAuth2 Bearer Token

Für neue Installationen würde ich Zugangsdaten nicht dauerhaft direkt in URLs hinterlegen, wenn sich Basic Authentication oder ein Token verwenden lässt.

Simple API nicht direkt ins Internet freigeben

Vom direkten Weiterleiten des Simple-API-Ports über den Router würde ich abraten. Wer von unterwegs auf ioBroker zugreifen möchte, sollte eine sichere Verbindung verwenden, beispielsweise über ein VPN.

Über die API können je nach Berechtigungen Datenpunkte verändert und damit auch Geräte gesteuert werden. Die Schnittstelle sollte deshalb genauso geschützt werden wie die ioBroker-Administrationsoberfläche.

CORS für Webanwendungen

Wenn eine Webanwendung aus einer anderen Domain auf die Simple API zugreifen soll, spielt außerdem CORS eine Rolle. In aktuellen Versionen kann in der Adapter-Konfiguration ein erlaubter Origin für den entsprechenden HTTP-Header eingetragen werden.

Für eine reine lokale Integration zwischen ESP32 und ioBroker wird diese Einstellung normalerweise nicht benötigt.

Beispiel: ESP32 sendet Temperatur an ioBroker

Ein typischer Einsatzbereich ist ein selbst gebauter Sensor. Angenommen, ein ESP32 misst eine Temperatur von 22,4 Grad.

Der Wert soll in diesem Datenpunkt gespeichert werden:

0_userdata.0.ESP32.Wohnzimmer.Temperatur

Der ESP32 kann anschließend folgenden HTTP-Aufruf an ioBroker senden:

http://192.168.178.50:8087/set/0_userdata.0.ESP32.Wohnzimmer.Temperatur?value=22.4

Damit lässt sich bereits mit sehr wenig Aufwand ein eigener Sensor an ioBroker anbinden.

Simple API mit iOS Kurzbefehlen

Eine weitere praktische Anwendung sind HTTP-Aufrufe aus Apples Kurzbefehle-App. Damit können beispielsweise ioBroker-Aktionen direkt vom iPhone ausgelöst werden.

Eine ausführliche Anleitung dazu findest du hier: iOS Kurzbefehle mit ioBroker verwenden.

Simple API funktioniert nicht: typische Fehler

Port 8087 ist nicht erreichbar

Prüfe zuerst, ob die Simple API als eigener Server oder als Web-Erweiterung konfiguriert wurde. Im Web-Erweiterungsmodus gibt es keinen separaten Simple-API-Port.

404 – Datenpunkt nicht gefunden

Kontrolliere die vollständige ID des Datenpunkts. Bereits ein falscher Punkt oder Buchstabe sorgt dafür, dass der State nicht gefunden wird.

403 – Zugriff nicht erlaubt

In diesem Fall fehlen dem verwendeten Benutzer normalerweise die notwendigen Rechte für den angeforderten Datenpunkt.

Wert wird nicht gesetzt

Prüfe den Datentyp des Datenpunkts. Ein State vom Typ Zahl sollte beispielsweise auch einen numerischen Wert erhalten.

Aufruf funktioniert im Browser, aber nicht in der Web-App

Dann kann eine fehlende CORS-Freigabe die Ursache sein. Prüfe die entsprechende Einstellung der Simple-API-Instanz.

Lohnt sich Simple API 2026 noch?

Für bestehende Projekte und einfache HTTP-Aufrufe ist die Simple API weiterhin praktisch. Ein Sensorwert lässt sich beispielsweise mit einer einzigen URL an ioBroker übertragen.

Bei einem komplett neuen Projekt würde ich zusätzlich den moderneren REST-API-Adapter prüfen. Die Simple API würde ich vor allem dann weiterverwenden, wenn bereits Geräte, Skripte oder Apps darauf zugreifen.

Fazit

Die ioBroker Simple API ist eine einfache Möglichkeit, ioBroker mit anderen Geräten und Anwendungen zu verbinden. Datenpunkte lassen sich per HTTP auslesen, setzen oder umschalten. Auch mehrere Werte können in einem einzigen Aufruf übertragen werden.

Wichtig ist bei aktuellen Installationen vor allem die Betriebsart des Adapters. Wer Simple API als Web-Erweiterung verwendet, kann sich nicht mehr automatisch auf den früher üblichen Port 8087 verlassen. Außerdem sollte die Schnittstelle immer ausreichend gegen unbefugte Zugriffe abgesichert werden.

Häufige Fragen zur ioBroker Simple API

Welchen Port verwendet ioBroker Simple API?

Bei einer eigenständigen Instanz ist häufig Port 8087 voreingestellt. Wird Simple API als Web-Erweiterung betrieben, verwendet der Adapter dagegen keinen eigenen lokalen Port.

Wie lese ich einen ioBroker-Datenpunkt per HTTP aus?

Für einen einzelnen Wert kann der Befehl getPlainValue verwendet werden. Mit get erhältst du zusätzlich weitere Informationen zum State als JSON.

Wie kann ich einen Datenpunkt verändern?

Dafür wird der Befehl set verwendet. Der gewünschte Wert wird über den Parameter value übergeben.

Brauche ich Simple API oder REST API?

Für bestehende und sehr einfache HTTP-Integrationen reicht Simple API häufig aus. Für neue und umfangreichere Projekte ist der neuere REST-API-Adapter ebenfalls einen Blick wert.

Kann ich Simple API mit ESP32 und ESP8266 verwenden?

Ja. Beide Mikrocontroller können HTTP-Anfragen senden und eignen sich daher gut für die Kommunikation mit einer lokalen Simple-API-Instanz.