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, cache up/down, memory, env, version). 503 only if the database is down; a cache-layer issue alone reports degraded but still returns 200. | 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 (database check, cache check); 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. API availability will be announced on Versioning & updates.
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:apply_link | URL to load + requestId | claim or link |
sign:link_rollback | requestId + reason; undo a link the kiosk applied | backend could not keep a link the kiosk had already applied (for example, its acknowledgement arrived after the backend gave up) |
sign:command | acknowledged command envelope; type is refresh, reboot, reboot_device, set_background_mode, content_push, unregister, settings_update, fetch_logs, or update | dashboard or mobile action, schedule, bulk action |
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
- Versioning & updates — where API availability will be announced