API overview
DisplaySync has no authenticated public API for end users. The REST + WebSocket endpoints at api.displaysync.live exist but are scoped for the dashboard, mobile app, and desktop sign — they're not designed, documented, or supported for third-party use. The only public endpoints are the three monitoring health checks documented immediately below, used by uptime monitors and orchestration layers.
This page exists so you can answer "is there an API?" with a clear "the health checks, and not much else, yet" instead of guessing, and so the workarounds for common automation needs are findable.
Health endpoints
Three public endpoints — no auth, not under /api, not rate-limited.
| Endpoint | Returns | Used by |
|---|---|---|
GET /health | Full subsystem flags (DB up/down, Redis up/down, memory, env, version). 200 healthy / 503 if DB down or Redis degraded. | Pingdom / StatusCake; on-call diagnostic |
GET /health/ready | DB readiness only. 200 if DB responsive, else 503. | Kubernetes-style readinessProbe; LB pool inclusion |
GET /health/live | Process liveness — no external calls. Always 200 with uptime. | Kubernetes-style livenessProbe; restart decisions |
/health/ready and /health/live are the right targets for orchestration probes — they're cheap and bounded. /health is fuller but does external calls (DB ping, Redis ping); use sparingly from external monitors. See Network requirements for the venue-IT smoke-test workflow against these.
Why no public API yet
The internal API is a moving target. Routes change without notice — internal callers update in lockstep, and that flexibility is load-bearing for shipping fast on a small team. A public API has different responsibilities (versioning, deprecation policy, rate-limit guarantees, customer SDKs) that we'd rather take on deliberately than backfill after the fact.
We're not opposed to shipping one. It's a question of when, not whether.
What you might want, and what you can do today
Most "I'd use the API for X" requests fall into a few buckets. Here's what works today without one:
| If you want to... | Today's path |
|---|---|
| Watch signs for offline state | Notifications — push and email, per-event subscriptions |
| React to content unreachability | Same — content_unreachable notifications |
| Bulk-update what walls show | Build content as a CMS-driven webpage and assign that URL once. Push to your CMS; signs see updates within their reachability check window. |
| Programmatic sign creation | Mobile-app claim is fast in practice — one tech can claim 30+ signs in an hour. Pre-create records in the dashboard for an even faster on-site flow (Flow B). |
| Pull sign status into a custom dashboard | Dashboard's audit log + content fetch logs are exportable; for richer needs, see pre-release access below. |
| Trigger a remote command from another system | A user with the right role + dashboard or mobile app. No automation hook today. |
The CMS-driven content pattern is the one we recommend most often. It moves the integration point from DisplaySync's API to your own content stack, where you have full control.
Pre-release access
If you have a concrete use case the patterns above don't cover, get in touch. For a small number of customers we work directly on what they need — sometimes that becomes part of the eventual public API; sometimes it's a one-off integration.
What helps when you reach out:
- A description of the workflow you're trying to automate
- The volume (how many signs / events / requests per day)
- Your timeline
- Whether you need read-only data or also write actions
Email [email protected] with [API EARLY ACCESS] in the subject. We'll either find a workaround using existing surfaces, or talk to you about an early-access arrangement.
No interface stability is promised for early access. If you build against a pre-release endpoint, you take the risk of routes changing.
When a public API ships
This page will be replaced with full reference material — endpoints, payloads, error responses, authentication, rate limits, webhooks — when the public API is available. Subscribe to the release notes to be notified.
Until then, the answer to most "what does the API offer?" questions is "contact us and we'll work it out together."
WebSocket event reference
DisplaySync uses Socket.io between dashboards/kiosks and the backend. The full event vocabulary, organized by direction. Cross-reference Glossary for terms like link_ack, pendingSign, requestId.
These events are not a public surface — they're scoped to first-party clients (dashboard, mobile app, desktop sign). Documented here so operators can reason about what travels over the WebSocket when triaging.
Kiosk → backend
| Event | What it carries | Triggered by |
|---|---|---|
sign:register | sign identity + device info | sign-app startup |
heartbeat | status + metrics + mode | kiosk timer (5s) |
sign:command_ack | command result | command execution complete |
sign:command_error | command failure | command execution failure |
sign:link_ack | link result + sub-reason | LinkAckHandler (handshake flow) |
sign:content_displayed | content render started | renderer event |
sign:content_error | content render failed | renderer error |
sign:content_unreachable | URL reachability check failed | reachability check |
sign:content_recovered | URL reachability check passed (post-failure) | reachability check |
sign:analytics | telemetry batch | kiosk timer or threshold |
sign:logs | recent log lines (Fetch Logs response) | dashboard request |
sign:update_status | electron-updater state | electron-updater event |
sign:claim_confirmed | claim acknowledgment | post-claim flow |
sign:status | status update from kiosk | (rarely used) |
sign:config_sync | config delta from kiosk | local config change |
Backend → kiosk
| Event | What it carries | Triggered by |
|---|---|---|
sign:config | full config snapshot | post-register / on-demand |
sign:claimed | sign claimed by user | claim flow |
sign:apply_link | URL to load + requestId | linkSign / claimSign with handshake |
sign:display_content | content piece to show | schedule fire / manual override |
sign:settings_update | partial settings patch | dashboard settings change |
sign:refresh | reload current URL | dashboard command |
sign:reboot | restart sign-app process | dashboard command |
sign:reboot_device | OS-level reboot | dashboard command |
sign:set_monitoring_mode | enter/exit monitoring mode | dashboard command |
sign:update | trigger electron-updater check | dashboard command |
sign:fetch_logs | request recent logs | dashboard command |
sign:unregistered | sign was unregistered | post-unregister flow |
sign:deleted | sign was deleted | post-delete flow |
heartbeat:ack | heartbeat received | per-heartbeat |
See also
- Notifications — the closest thing to a webhook for sign-state changes today
- Operations → Remote control — the dashboard- and mobile-app-driven actions that would otherwise be API targets
- Releases — where API availability will be announced