API reference (v1)

OOHLEMON's public REST API: control displays, read content, build automations. Base URL: https://v2.api.oohlemon.com/api/v1

Back to documentation

Requirement: Pro plan

The REST API and webhooks are included in the Pro plan (€12/month). Create API keys in the dashboard under Integrations → API keys. Each account can have up to 10 active keys (personal and team keys counted separately). A key is shown in plain text only once — copy it straight away.

Authentication

All requests authenticate with a bearer token in the Authorization header using your API key. Keys are bound to your account (or team) and inherit its permissions. After several failed attempts the API temporarily locks the key.

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

(--oauth2-bearer is the curl shorthand for an Authorization header with a bearer token.)

Endpoints

The API is a JSON REST API at https://v2.api.oohlemon.com/api/v1. Read endpoints are available on every key; write operations (PATCH, POST) require a key with write access.

Method	Path	Description
GET	/me	Fetch the account and permissions of the API key — the classic connection test.
GET	/devices	List all displays (status, name, location); ?online=true/false filter, cursor pagination.
GET	/devices/{id}	One display in detail: status, name, description, assigned schedule.
PATCH	/devices/{id}	Rename a display, edit its description and assign a schedule (schedule_id) — write access.
POST	/devices/{id}/commands	Send a command to the player: reload_playlist, restart_app, clear_cache or reboot (write access).
GET	/media	List the media library — images, videos, documents.
GET	/media/{id}	One media file in detail (metadata, status).
GET	/playlists	List all playlists.
GET	/playlists/{id}	One playlist with all items and durations.
GET	/schedules	List all schedules.
GET	/schedules/{id}	One schedule in detail (time windows, weekdays).
GET	/campaigns	List campaigns (DOOH advertising).
GET	/campaigns/{id}	One campaign in detail.

Device control without writing code: the four player commands (reload_playlist, restart_app, clear_cache, reboot) cover the most common remote cases.

Example requests

List displays

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

Response (abridged): { "data": [ … ], "has_more": false } — cursor pagination with limit (max. 100) and starting_after; if the response contains next_cursor, there are more pages. Use ?online=true or ?online=false to filter devices with or without a recent check-in.

Reload a playlist on a display

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

POST requests accept an optional Idempotency-Key header — repeated identical requests then return the same result for 24 hours instead of executing twice. Commands take effect on the player's next heartbeat — depending on connectivity this can take up to 5 minutes.

Rate limits

600

requests per minute

120

write operations per minute

active keys per account

Every response carries the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. When exceeded, the API responds with status 429 and a Retry-After header — your client should respect it and retry with backoff.

Webhooks & signature verification

Webhooks are the counterpart to the API: instead of polling data, you get notified when events happen. Available event types, grouped by area:

Displays

device.offline

A display has not checked in within the expected window

device.online

A display is reachable again

device.paired

A new display was paired with the account

Campaigns

campaign.started

A campaign has started

campaign.finished

A campaign has ended

campaign.rejected

A submitted campaign was rejected

Media

media.ready

A media file finished processing and is ready to use

media.failed

Processing of a media file failed

Playlists & schedules

playlist.updated

A playlist was changed

schedule.updated

A schedule was changed

Every webhook delivery carries an OOHLEMON-Signature header (format t=<unix>,v1=<hex>) plus event id and event type. The signature is an HMAC-SHA256 over t + "." + raw body using your endpoint secret — this proves the event really came from OOHLEMON and was not altered. Tolerance: 5 minutes. Zapier, Make and n8n are covered step by step in the integrations guide.

Error format

Errors always respond in the same JSON shape with a meaningful code and a request_id you can quote to support:

{
  "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_…"
  }
}

Ready for your first automation?

Try all Pro features free for 14 days — create your API key right in the dashboard.

Start for free

As of: October 2026 · The API evolves continuously: existing fields stay as stable as possible, new fields are added and flagged in the docs.