CMS developer API

Request the add-on

1. An organisation owner opens Organisation profile → Developer API and selects Request add-on. Tell DOOXOOH what you want to connect and agree the scope and commercial terms with our team.
2. Your request stays pending until DOOXOOH approves it. Requesting access does not enable the API. Contact support to change or cancel access.

Create a connection after approval

1. After approval, open Organisation profile → Developer API as the organisation owner. Enter a connection name, choose the required read permissions and select an expiry.
2. Select Create API key and save the key when it appears. Keep it in your integration’s server-side secret storage. Never place it in a public webpage, mobile app bundle or URL.
3. Use a separate key for each integration. Revoke keys you no longer use and replace expiring keys before updating your integration.

Authenticate a request

1. Base URL: https://cms.dooxooh.com/api/v1. Send your key in the Authorization header on every request. Requests return JSON.

GET /api/v1/screens?status=online&limit=50
Authorization: Bearer YOUR_CMS_API_KEY

Available endpoints

1. GET /screens — list screens with status and player health. GET /screens/{screen_id} — read one screen. GET /screens/summary — read total, online, offline and unpaired screen counts. These endpoints require screens:read.
2. GET /venues — list venue details. GET /regions — list regions. These endpoints require places:read.
3. Access is limited to your organisation and the read permissions selected for the key. This API does not change content, schedules or devices.

Filter and paginate

1. Screen list filters: status (all, online, offline or unpaired), venue_id, region_id, limit (1–100; default 50) and after.
2. Summary filters: venue_id and region_id. Single-screen requests take no list filters.
3. Venue filters: venue_id, region_id, limit and after. Region filters: region_id, limit and after.
4. List responses include data and pagination. While pagination.has_more is true, pass pagination.next_cursor as after on the next request. Keep the other filters unchanged.

Understand screen status

1. online means a paired player has reported within the current offline threshold. offline means a paired player has not reported recently. unpaired means the screen has not been paired.
2. Online status is a recent player connection signal; it does not confirm that a TV panel is on or that an advert was visible. Read last_seen and as_of with the status.
3. Screen records include id, name, platform, width, height, paired_at, venue_id, venue_name, region_id, region_name, status, online, last_seen, player_version, free_bytes, queued_reports, download_status, download_percent and has_error. Values may be null when unavailable.
4. Responses include api_version, resource, organization_id, as_of, offline_after_seconds, data and pagination. Summary data contains total, online, offline and unpaired. Venue data includes id, name, address, timezone, playback_mode, region_id and region_name. Region data includes id, name, region and country. Archived items are excluded.

Handle limits and errors

1. Each key allows up to 60 requests per minute. Prefer polling every 30–60 seconds and reusing results. Read X-RateLimit-Remaining; on HTTP 429, wait for Retry-After.
2. HTTP 400 means a request needs correcting. HTTP 401 means the key is unavailable or no longer valid. HTTP 403 means the required permission or approved add-on access is unavailable. HTTP 404 means the resource is unavailable. HTTP 503 means the service is temporarily unavailable; retry later or contact support.
3. Errors use an error object containing code and message. Never send your API key to support.

Example: fetch offline screens

1. Run this example in your backend, with DOOXOOH_CMS_API_KEY stored securely. Check errors and follow pagination when needed.

const response = await fetch(
  'https://cms.dooxooh.com/api/v1/screens?status=offline&limit=100',
  { headers: { Authorization: `Bearer ${process.env.DOOXOOH_CMS_API_KEY}` } }
);
if (!response.ok) throw new Error(`CMS API returned ${response.status}`);
const result = await response.json();
for (const screen of result.data) {
  console.log(screen.name, screen.status, screen.last_seen);
}