Versions
v4.1 is the current version and a superset of v4. v3 was switched off on October 1, 2026, apart from adding and removing screens.
Three versions have existed. Two of them still respond in full.
| Version | Base | Status |
|---|---|---|
| v4.1 | https://api.screenlyapp.com/api/v4.1/ | Current. Target this |
| v4 | https://api.screenlyapp.com/api/v4/ | Still responds, and is a subset of v4.1 |
| v3 | https://api.screenlyapp.com/api/v3/ | Switched off on October 1, 2026, apart from adding and removing screens |
Use v4.1
Stable since May 2026, and what new work should target. Tokens you already have work with it; there is nothing to reissue.
It is a superset of v4: every v4 path exists in v4.1, under the /v4.1/ segment instead of /v4/.
Four paths exist only in v4.1, and they are the ones you are most likely to want:
| Path | What it gives you |
|---|---|
/v4.1/screens/statuses | status, in_sync, and is_online per screen |
/v4.1/screens/reports | The health report a device sends |
/v4.1/screens/pings | When each screen last checked in |
/v4.1/screens/configs | A screen's delivered configuration |
That first one matters more than it looks. On v4.1 a screen's status is not on the screen record, so "which of my screens are offline" cannot be answered from /v4.1/screens at all. It needs /v4.1/screens/statuses. What the values mean is in Screen status and health.
Moving from v4 to v4.1
Change the segment. For most paths, nothing else changes.
/screens is the exception. On v4 the screen record itself carries status, in_sync, last_ping, and fields from the device's report. On v4.1 the screen record holds only what you configured, and those values move to /v4.1/screens/statuses, /v4.1/screens/pings, and /v4.1/screens/reports.
v4 is not being switched off and no date has been announced for it. It is missing everything added since, so there is no reason to start something new on it.
What is left of v3
Since October 1, 2026, the v3 endpoints for screens, playlists, groups, and assets no longer work. Requests to /api/v3/assets/, /api/v3/groups/, /api/v3/playlists/, and /api/v3/screens/ get a 410 Gone response, and so do the URLs for a single item under them, such as /api/v3/screens/<id>/.
2 calls still work, so that older versions of the CLI can add and remove screens:
POST /api/v3/screens/adds a screen.DELETE /api/v3/screens/<id>/removes one.
Don't build on them. They exist for old CLI versions, not for new integrations.
The same data is in v4.1:
| v3 | v4.1 |
|---|---|
/api/v3/assets/ | /v4.1/assets |
/api/v3/groups/ | /v4.1/labels |
/api/v3/playlists/ | /v4.1/playlists |
/api/v3/screens/ | /v4.1/screens |
v3 is a different API rather than an older version of this one, so moving off it is a rewrite of the calls, not a change of segment. If you are not sure whether anything of yours is still on v3, grep your own code and CI configuration for /v3/.
The schema
Every endpoint, field, and filter is in the v4.1 API reference.