API-Referenz (v1)

Die öffentliche REST-API von OOHLEMON: Displays steuern, Inhalte auslesen, Automatisierungen bauen. Basis-URL: https://v2.api.oohlemon.com/api/v1

Zur Dokumentation

Voraussetzung: Pro-Paket

Die REST-API und Webhooks sind im Pro-Paket (12 €/Monat) enthalten. API-Schlüssel erstellen Sie im Dashboard unter Integrationen → API-Schlüssel. Pro Konto sind bis zu 10 aktive Schlüssel möglich (persönliche und Team-Schlüssel getrennt gezählt). Ein Schlüssel wird nur einmal im Klartext angezeigt — kopieren Sie ihn sofort.

Authentifizierung

Alle Anfragen authentifizieren sich per Bearer-Token im Authorization-Header mit Ihrem persönlichen API-Schlüssel. Schlüssel sind an Ihr Konto (bzw. Team) gebunden und erben dessen Berechtigungen. Nach mehreren fehlgeschlagenen Versuchen sperrt die API den Schlüssel vorübergehend.

curl https://v2.api.oohlemon.com/api/v1/me \
  --oauth2-bearer IHR_API_SCHLUESSEL

(--oauth2-bearer ist das curl-Kürzel für den Authorization-Header mit Bearer-Token.)

Endpunkte

Die API ist eine JSON-REST-API unter https://v2.api.oohlemon.com/api/v1. Lese-Endpunkte sind überall verfügbar, Schreibzugriffe (PATCH, POST) benötigen einen Schlüssel mit Schreibrecht.

Methode	Pfad	Beschreibung
GET	/me	Konto und Berechtigungen des API-Schlüssels abrufen — der klassische Verbindungstest.
GET	/devices	Alle Displays auflisten (Status, Name, Standort); Filter ?online=true/false, Cursor-Pagination.
GET	/devices/{id}	Ein Display im Detail: Status, Name, Beschreibung, zugewiesener Zeitplan.
PATCH	/devices/{id}	Display umbenennen, Beschreibung pflegen und einen Zeitplan zuweisen (schedule_id) — Schreibzugriff.
POST	/devices/{id}/commands	Befehl an den Player senden: reload_playlist, restart_app, clear_cache oder reboot (Schreibzugriff).
GET	/media	Mediathek auflisten — Bilder, Videos, Dokumente.
GET	/media/{id}	Ein Medium im Detail (Metadaten, Status).
GET	/playlists	Alle Playlists auflisten.
GET	/playlists/{id}	Eine Playlist mit allen Elementen und Dauern.
GET	/schedules	Alle Zeitpläne auflisten.
GET	/schedules/{id}	Ein Zeitplan im Detail (Zeitfenster, Wochentage).
GET	/campaigns	Kampagnen (DOOH-Werbung) auflisten.
GET	/campaigns/{id}	Eine Kampagne im Detail.

Gerätesteuerung ohne eigene Programmierung: Die vier Player-Befehle (reload_playlist, restart_app, clear_cache, reboot) decken die häufigsten Remote-Fälle ab.

Beispiel-Requests

Displays auflisten

curl https://v2.api.oohlemon.com/api/v1/devices \
  --oauth2-bearer IHR_API_SCHLUESSEL

Antwort (gekürzt): { "data": [ … ], "has_more": false } — Cursor-Pagination mit limit (max. 100) und starting_after; enthält die Antwort next_cursor, gibt es weitere Seiten. Mit ?online=true bzw. ?online=false filtern Sie nach Geräten mit bzw. ohne aktueller Meldung.

Playlist auf einem Display neu laden

curl -X POST https://v2.api.oohlemon.com/api/v1/devices/DISPLAY_ID/commands \
  --oauth2-bearer IHR_API_SCHLUESSEL \
  -H "Content-Type: application/json" \
  -d '{"command": "reload_playlist"}'

Bei POST-Anfragen können Sie optional einen Idempotency-Key-Header mitsenden — wiederholte identische Requests liefern dann 24 Stunden lang dasselbe Ergebnis statt doppelt ausgeführt zu werden. Befehle greifen beim nächsten Heartbeat des Players — je nach Verbindung kann das bis zu 5 Minuten dauern.

Rate-Limits

600

Requests pro Minute

120

Schreib-Operationen pro Minute

aktive Schlüssel pro Konto

Jede Antwort enthält die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Bei Überschreitung antwortet die API mit Status 429 und einem Retry-After-Header — Ihr Client sollte das respektieren und mit Backoff retryen.

Webhooks & Signaturprüfung

Webhooks sind das Gegenstück zur API: Statt Daten abzufragen, werden Sie bei Events benachrichtigt. Verfügbare Event-Typen, gruppiert nach Bereich:

Displays

device.offline

Ein Display meldet sich nicht mehr innerhalb des erwarteten Zeitfensters

device.online

Ein Display ist wieder erreichbar

device.paired

Ein neues Display wurde mit dem Konto gekoppelt

Kampagnen

campaign.started

Eine Kampagne hat begonnen

campaign.finished

Eine Kampagne ist beendet

campaign.rejected

Eine eingereichte Kampagne wurde abgelehnt

Medien

media.ready

Ein Medium ist verarbeitet und einsatzbereit

media.failed

Die Verarbeitung eines Mediums ist fehlgeschlagen

Playlists & Zeitpläne

playlist.updated

Eine Playlist wurde geändert

schedule.updated

Ein Zeitplan wurde geändert

Jede Webhook-Zustellung enthält die Header OOHLEMON-Signature (Format t=<unix>,v1=<hex>) sowie Event-Id und Event-Type. Die Signatur ist ein HMAC-SHA256 über t + "." + roher Body mit Ihrem Endpoint-Secret — so stellen Sie sicher, dass das Event wirklich von OOHLEMON kommt und nicht verändert wurde. Toleranz: 5 Minuten. Zapier, Make und n8n prüfen wir in der Integrations-Anleitung Schritt für Schritt.

Fehlerformat

Fehler antworten immer im gleichen JSON-Format mit aussagekräftigem code und einer request_id, die Sie beim Support angeben können:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_command",
    "message": "command must be one of: reload_playlist, restart_app, clear_cache, reboot.",
    "param": "command",
    "request_id": "req_…"
  }
}

Bereit für Ihre erste Automatisierung?

14 Tage alle Pro-Funktionen testen — API-Schlüssel direkt im Dashboard erstellen.

Kostenlos starten

Stand: Oktober 2026 · Die API wird kontinuierlich weiterentwickelt: Bestehende Felder bleiben so stabil wie möglich, neue Felder kommen hinzu und werden in der Doku gekennzeichnet.