Three versions have existed. Two of them still respond.
| 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 1 October 2026 |
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 with the same shape, 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 | is_online and in_sync per screen |
/v4.1/screens/reports | The health report a device sends |
/v4.1/screens/pings | Check-in history |
/v4.1/screens/configs | A screen’s delivered configuration |
That first one matters more than it looks. A screen’s status is not on the screen record, so “which of my screens are offline” cannot be answered from /screens at all, in either version. It needs /v4.1/screens/statuses, which does not exist in v4.
Moving from v4 to v4.1
Change the segment. Nothing else, for the nine paths that exist in both.
v4 is not being switched off and no date has been announced for it. It is simply missing everything added since, so there is no reason to start something new on it.
v3 is being switched off
All v3 endpoints (api.screenlyapp.com/api/v3/*) stop responding on 1 October 2026. There is no partial shutdown, no read-only mode, and no grace period. Anything still calling v3 after that date fails.
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. It is worth starting well before the date.
If you are not sure whether anything of yours is on v3, the cheapest check is to grep your own code and CI configuration for /v3/ while there is still time to act on the answer.
The schema
Every endpoint, field, and filter is in the v4.1 API reference.