REST API

Authentication

Create a token in the dashboard under Settings → API tokens (Admin or Super Admin only). The token is shown once — copy it then. Send it as a bearer token on every request:

Authorization: Bearer dg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

All endpoints are served by your own server — there is no DisplayGrid cloud. Use your server’s address:

• Desktop Server App: http://<host>:5555
• Docker / run-from-source: http://<host>:3000

Examples below use $DG for the base URL and $TOKEN for your token.

Emergency override

Broadcast a full-screen message to every display at once, or clear it.

GET /api/emergency-override

Returns the active override, or null if none.

curl -H "Authorization: Bearer $TOKEN" $DG/api/emergency-override

POST /api/emergency-override

Activates an override. Body fields:

curl -X POST $DG/api/emergency-override \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Fire — evacuate now","activeMinutes":30}'

DELETE /api/emergency-override

Clears the override; screens resume normal playback.

curl -X DELETE -H "Authorization: Bearer $TOKEN" $DG/api/emergency-override

Screens

GET /api/screens

Lists every screen with its pairing token, zone, resolution, and live online/last-seen status — useful for monitoring displays from an external dashboard.

curl -H "Authorization: Bearer $TOKEN" $DG/api/screens

Playlists

GET /api/playlists

Lists playlists with their screen, active state, and slide count.

curl -H "Authorization: Bearer $TOKEN" $DG/api/playlists

Recipes

Panic button (Home Assistant)

Wire a physical button or automation to a REST command that fires the override:

rest_command:
  displaygrid_evacuate:
    url: "http://192.168.1.10:5555/api/emergency-override"
    method: POST
    headers:
      authorization: "Bearer dg_your_token"
      content-type: "application/json"
    payload: '{"message":"Evacuate the building now"}'

Alert when a screen goes offline (cron)

# every 5 minutes, warn if any screen hasn't checked in recently
curl -s -H "Authorization: Bearer $TOKEN" $DG/api/screens \
  | jq -r '.[] | select(.online == false) | .name'