Download OpenAPI specification:
Beta — This API is currently in beta. If you encounter any issues or have feedback, please get in touch.
The AbleSign API allows you to manage your digital signage screens, content, and playlists programmatically. New to the API? See the Getting Started guide.
All requests require an API key passed as a Bearer token in the Authorization header:
Authorization: Bearer ak_your_api_key_here
API keys can be created in the AbleSign CMS under Account > API Keys.
If your account has multiple workspaces, include a Workspace-Id header to specify which workspace to operate on:
Workspace-Id: 123
If omitted, the default workspace is used.
List endpoints return paginated results. Use limit and offset query parameters to control pagination.
The response includes totalItems, limit, and offset metadata.
Default limit is 25. Maximum limit is 200.
Error responses follow a consistent format:
{
"status": "error",
"code": "ERROR_CODE",
"message": "Human-readable description"
}
| Code | HTTP Status | Description |
|---|---|---|
VALIDATION_ERROR |
400 | Invalid request parameters or body |
NOT_FOUND |
404 | Resource not found |
UNSUPPORTED_FILE_TYPE |
400 | File type is not supported |
FILE_TYPE_MISMATCH |
400 | Replacement file must match the original type |
FILE_SIZE_TOO_LARGE |
400 | File exceeds the maximum allowed size |
STORAGE_LIMIT_EXCEEDED |
413 | Organization storage limit reached |
UPLOAD_RATE_LIMIT_EXCEEDED |
429 | Too many uploads in a short period |
UNABLE_TO_PROCESS_FILE |
500 | Server failed to process the uploaded file |
PLAYLIST_LIMIT_EXCEEDED |
400 | Playlist has too many items; a standalone playlist item counts for the items it plays |
BATCH_LIMIT_EXCEEDED |
400 | Too many items in a batch operation |
ALREADY_REGISTERED |
409 | Screen registration code already in use |
RESOURCE_LIMIT_REACHED |
400 | Maximum number of resources reached for your organization |
RATE_LIMIT_EXCEEDED |
429 | Too many requests — try again shortly |
RATE_LIMITED |
429 | Per-key or per-IP request limit reached; see Rate limits |
SCREEN_IN_GROUP |
409 | The screen is in a screen group; write its playlists and layout through the group |
ZONE_CONTENT_NOT_ALLOWED |
400 | Video can only play in a layout's main zone |
SUB_PLAYLIST_NOT_ALLOWED |
400 | A standalone playlist item can only be in a layout's main zone |
SUB_PLAYLIST_IS_ITSELF |
400 | A standalone playlist cannot be an item of itself |
SUB_PLAYLIST_CONTAINS_HOST |
400 | A standalone playlist that already holds this one cannot be an item of it |
SUB_PLAYLIST_TOO_DEEP |
400 | Standalone playlists nest at most 3 deep under a screen's playlist |
HOST_PLAYLIST_LIMIT_EXCEEDED |
400 | A playlist that plays this standalone playlist would play more than 100 items |
CANNOT_DELETE_DEFAULT |
400 | The default workspace cannot be deleted |
WORKSPACE_HAS_USERS |
409 | Workspace has assigned users and cannot be deleted |
WORKSPACE_HAS_CONTENT |
409 | Workspace contains screens, media files, or web apps and cannot be deleted |
The API applies rate limits to protect the platform:
| Operation | Limits | Scope |
|---|---|---|
| All requests | 500 per rolling 5 minutes | Per API key |
| All requests | 2000 per rolling 5 minutes | Per client IP address |
| Playlist and layout writes (save playlist, add items, update item, save a zone playlist, apply a layout) | 15/min, 30/hr | Per screen, screen group or standalone playlist |
| Replace file | 5/min, 20/hr | Per media file |
| Update web app | 5/min, 20/hr | Per web app |
| Set screen group members | 5/min, 20/hr | Per screen group |
| File uploads | 200/day (default) | Per organization |
When a limit is exceeded the API returns a 429 status code. The per-key and per-IP limits are enforced at the edge and return a RATE_LIMITED error code with a Retry-After: 60 header. The per-operation limits return a RATE_LIMIT_EXCEEDED error code. In both cases wait for the window to pass before retrying.
The per-key limit counts every request made with the key, across all endpoints and all callers sharing it. Polling every screen in a loop is the usual way to reach it: fetch the screen list once, request individual screens only when you need their detail, and spread requests out rather than sending them in bursts.
Returns a paginated list of screens in the active workspace.
| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" "heartbeat_date_asc" "heartbeat_date_desc" Sort order |
| orientations | string Comma-separated orientation filter (landscape, portrait, reverse_landscape, reverse_portrait) |
| onlineStatus | string Comma-separated status filter (online, offline) |
| screenTags | string Comma-separated tag filter |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "description": "string",
- "orientation": "landscape",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "heartbeatTime": "2019-08-24T14:15:22Z",
- "softwareVersionCode": 0,
- "screenGroupId": 0,
- "popEnabled": true,
- "demo": true,
- "screenTags": [
- {
- "name": "string"
}
]
}
]
}Register a new screen using a pairing code displayed on the device. The player app on the
device must be recent enough to pair; an older one is refused with PLAYER_APP_OUT_OF_DATE
and its code stays waiting, so update the app on the device and pair it again.
| registrationCode required | string^[0-9]{6}$ The 6-digit code displayed on the device |
| title required | string <= 255 characters |
| description | string <= 255 characters |
| orientation required | string Enum: "landscape" "portrait" "reverse_portrait" "reverse_landscape" |
{- "registrationCode": "string",
- "title": "string",
- "description": "string",
- "orientation": "landscape"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "orientation": "landscape",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "heartbeatTime": "2019-08-24T14:15:22Z",
- "softwareVersionCode": 0,
- "screenGroupId": 0,
- "popEnabled": true,
- "demo": true,
- "screenTags": [
- {
- "name": "string"
}
], - "fitItem": "CenterCrop",
- "webPageBackground": "string",
- "timezone": "string",
- "model": "string",
- "manufacturer": "string",
- "softwareVersionName": "string",
- "syncEnabled": true,
- "syncRole": "leader",
- "syncLeaderScreenId": 0,
- "screenOperatingHour": {
- "enabled": true,
- "cecControl": true,
- "workingMode": "on_hours",
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}, - "capabilities": {
- "zones": {
- "supported": true,
- "reasons": [
- "string"
]
}
}
}
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "orientation": "landscape",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "heartbeatTime": "2019-08-24T14:15:22Z",
- "softwareVersionCode": 0,
- "screenGroupId": 0,
- "popEnabled": true,
- "demo": true,
- "screenTags": [
- {
- "name": "string"
}
], - "fitItem": "CenterCrop",
- "webPageBackground": "string",
- "timezone": "string",
- "model": "string",
- "manufacturer": "string",
- "softwareVersionName": "string",
- "syncEnabled": true,
- "syncRole": "leader",
- "syncLeaderScreenId": 0,
- "screenOperatingHour": {
- "enabled": true,
- "cecControl": true,
- "workingMode": "on_hours",
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}, - "capabilities": {
- "zones": {
- "supported": true,
- "reasons": [
- "string"
]
}
}
}
}Partial update — only include the fields you want to change.
| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string <= 255 characters |
| orientation | string Enum: "landscape" "portrait" "reverse_portrait" "reverse_landscape" Display orientation of the screen |
| fitItem | string Enum: "CenterCrop" "FitXY" How content is scaled to fit the screen (CenterCrop = fill and crop, FitXY = scale to fit with letterboxing) |
| webPageBackground | string^#[0-9A-Fa-f]{6}$ Hex colour painted behind a web page in the main zone where the page has no background of its own (default #ffffff); zones use their own background |
| timezone | string <= 255 characters IANA timezone for the screen (e.g. Europe/London) |
| screenTags | Array of strings Tags to assign to this screen (replaces existing tags) |
| syncEnabled | boolean Whether playlist synchronization with another screen is enabled |
| syncRole | string Enum: "leader" "follower" Role in playlist sync — leader controls playback timing, follower mirrors it. Leave it out to keep the current role; changing a leader to follower stops sync on the screens that follow it |
| syncLeaderScreenId | integer or null ID of the leader screen (required when syncRole is follower) |
{- "title": "string",
- "description": "string",
- "orientation": "landscape",
- "fitItem": "CenterCrop",
- "webPageBackground": "string",
- "timezone": "string",
- "screenTags": [
- "string"
], - "syncEnabled": true,
- "syncRole": "leader",
- "syncLeaderScreenId": 0
}{- "status": "success"
}Partial update — only include the fields you want to change. Days that are omitted keep their
current times. A day's start and end must always be sent together (a start without its end, or
vice versa, is rejected). Set both to null to switch the screen off for that day (or, in
off_hours mode, to leave it on all day); a null start means from midnight and a null end
means until 23:59. Times are HH:mm or HH:mm:ss and are evaluated in the screen's timezone.
| id required | integer |
| enabled | boolean Whether the screen is turned off outside its operating hours. |
| cecControl | boolean Whether the screen uses HDMI-CEC to power the display on/off |
| workingMode | string Enum: "on_hours" "off_hours" on_hours = screen is on during specified times, off_hours = screen is off during specified times |
| monStart | string or null Monday start time (HH:mm:ss). |
| monEnd | string or null Monday end time (HH:mm:ss). |
| tueStart | string or null Tuesday start time (HH:mm:ss). |
| tueEnd | string or null Tuesday end time (HH:mm:ss). |
| wedStart | string or null Wednesday start time (HH:mm:ss). |
| wedEnd | string or null Wednesday end time (HH:mm:ss). |
| thuStart | string or null Thursday start time (HH:mm:ss). |
| thuEnd | string or null Thursday end time (HH:mm:ss). |
| friStart | string or null Friday start time (HH:mm:ss). |
| friEnd | string or null Friday end time (HH:mm:ss). |
| satStart | string or null Saturday start time (HH:mm:ss). |
| satEnd | string or null Saturday end time (HH:mm:ss). |
| sunStart | string or null Sunday start time (HH:mm:ss). |
| sunEnd | string or null Sunday end time (HH:mm:ss). |
{- "enabled": true,
- "workingMode": "on_hours",
- "monStart": "09:00",
- "monEnd": "17:00",
- "satStart": null,
- "satEnd": null
}{- "status": "success"
}The playlist of the main zone of the screen's layout. A layout's other zones are read and written through /screens/{id}/zones/{zoneId}/playlist.
| id required | integer |
{- "status": "success",
- "data": {
- "shufflePlay": true,
- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "items": [
- {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}
}Replaces the entire playlist. Send all items — existing items not included will be removed.
| id required | integer |
| defaultTransition | string or null |
| defaultTransitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| enableImageTransitions | boolean |
| enableWebappTransitions | boolean |
| shufflePlay | boolean |
required | Array of objects <= 100 items At most 100 items, counting what the playlist plays: a standalone playlist item counts for every item its standalone playlist plays. |
{- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "shufflePlay": true,
- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "sequenceNumber": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}{- "status": "success"
}Adds one or more items to a screen's existing playlist without replacing it. The playlist may then play at most 100 items, a standalone playlist item counting for every item it plays (PLAYLIST_LIMIT_EXCEEDED).
| id required | integer |
required | Array of objects [ 1 .. 50 ] items |
| position required | string Enum: "start" "end" Where to insert the items in the playlist |
{- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "scheduleEnabled": true,
- "periodicScheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "monStart": "09:00",
- "monEnd": "17:00",
- "tueStart": "09:00",
- "tueEnd": "17:00",
- "wedStart": "09:00",
- "wedEnd": "17:00",
- "thuStart": "09:00",
- "thuEnd": "17:00",
- "friStart": "09:00",
- "friEnd": "17:00",
- "satStart": "09:00",
- "satEnd": "17:00",
- "sunStart": "09:00",
- "sunEnd": "17:00"
}
], - "position": "start"
}{- "status": "success"
}Partially updates a single item on a screen's playlist. Only the fields included in the request body are changed; omitted fields keep their current values. A day's start and end times (monStart/monEnd etc.) must be sent together; send both as null to clear that day's window.
mediafileId, webAppId, standalonePlaylistId and sequenceNumber cannot be changed here; to swap content or reorder, use PUT /screens/{id}/playlist.
A standalone playlist item has only its schedule to change: displayDuration, transition or transitionSpeedLabel sent for one is refused with VALIDATION_ERROR.
| id required | integer |
| itemId required | integer ID of the playlist item to update |
| displayDuration | integer [ 0 .. 9999999 ] Display duration in seconds. Overridden by video duration for video files. |
| transition | string or null |
| transitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| scheduleEnabled | boolean When true, the item is only shown during the daily time windows defined by monStart/monEnd through sunStart/sunEnd |
| periodicScheduleEnabled | boolean When true, the item uses a periodic schedule defined by scheduleStartDate, scheduleEndDate, and scheduleRrule |
| scheduleStartDate | string or null <date-time> |
| scheduleEndDate | string or null <date-time> |
| scheduleRrule | string or null iCal RRULE for recurring schedule, in a layout the CMS writes: FREQ=DAILY; FREQ=WEEKLY with or without BYDAY; FREQ=MONTHLY with BYMONTHDAY, or with BYSETPOS and optionally BYDAY; FREQ=YEARLY with BYMONTH and either BYMONTHDAY, or BYSETPOS and optionally BYDAY. Any of them may add INTERVAL (up to 520) and COUNT or UNTIL, not both. BYMONTH, BYMONTHDAY and BYSETPOS take one value, BYDAY takes weekdays without a position (MO,WE, not 1MO), and each part is given once. Anything else, BYHOUR and BYMINUTE among it, is refused with VALIDATION_ERROR. |
| monStart | string or null Monday start time (HH:mm). |
| monEnd | string or null Monday end time (HH:mm). |
| tueStart | string or null Tuesday start time (HH:mm). |
| tueEnd | string or null Tuesday end time (HH:mm). |
| wedStart | string or null Wednesday start time (HH:mm). |
| wedEnd | string or null Wednesday end time (HH:mm). |
| thuStart | string or null Thursday start time (HH:mm). |
| thuEnd | string or null Thursday end time (HH:mm). |
| friStart | string or null Friday start time (HH:mm). |
| friEnd | string or null Friday end time (HH:mm). |
| satStart | string or null Saturday start time (HH:mm). |
| satEnd | string or null Saturday end time (HH:mm). |
| sunStart | string or null Sunday start time (HH:mm). |
| sunEnd | string or null Sunday end time (HH:mm). |
{- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "periodicScheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "monStart": "09:00",
- "monEnd": "17:00",
- "tueStart": "09:00",
- "tueEnd": "17:00",
- "wedStart": "09:00",
- "wedEnd": "17:00",
- "thuStart": "09:00",
- "thuEnd": "17:00",
- "friStart": "09:00",
- "friEnd": "17:00",
- "satStart": "09:00",
- "satEnd": "17:00",
- "sunStart": "09:00",
- "sunEnd": "17:00"
}{- "status": "success",
- "data": {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
}The zones the screen shows, the main zone first, and what the layout was made from. For a screen in a screen group this is the group's layout.
| id required | integer |
{- "status": "success",
- "data": {
- "preset": "main_sidebar",
- "layoutId": 0,
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent",
- "layoutZoneId": 0
}
]
}
}Replaces the screen's layout with a preset or with one of the workspace's layouts. Send exactly one of preset and layoutId. The response is the new layout, with the ID of each zone.
The main zone and its playlist are kept. Another zone keeps its playlist only when the new layout has a zone to match it (the same zone of the same layout, or else a zone with the same name); zones with no match are deleted with their playlists, and new zones start empty. Apply full_screen to go back to a single zone.
| id required | integer |
| preset | string <= 32 characters Key of a preset from |
| layoutId | integer ID of a layout from |
{- "preset": "main_sidebar"
}{- "status": "success",
- "data": {
- "preset": "main_sidebar",
- "layoutId": 0,
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent",
- "layoutZoneId": 0
}
]
}
}The playlist of one zone of the screen's layout. Zone IDs come from GET /screens/{id}/layout. For the main zone this is the same playlist as GET /screens/{id}/playlist.
| id required | integer |
| zoneId required | integer ID of a zone of the screen's or screen group's layout, from its |
{- "status": "success",
- "data": {
- "shufflePlay": true,
- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "items": [
- {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}
}Replaces the entire playlist of one zone. Send all items — existing items not included will be removed. Zones other than the main zone take images and web apps only; a standalone playlist item goes in the main zone only.
| id required | integer |
| zoneId required | integer ID of a zone of the screen's or screen group's layout, from its |
| defaultTransition | string or null |
| defaultTransitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| enableImageTransitions | boolean |
| enableWebappTransitions | boolean |
| shufflePlay | boolean |
required | Array of objects <= 100 items At most 100 items, counting what the playlist plays: a standalone playlist item counts for every item its standalone playlist plays. |
{- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "shufflePlay": true,
- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "sequenceNumber": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}{- "status": "success"
}| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" Sort order |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "screens": [
- {
- "id": 0
}
]
}
]
}| title required | string <= 255 characters |
| description | string <= 255 characters |
{- "title": "string",
- "description": "string"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "screens": [
- {
- "id": 0
}
], - "description": "string",
- "orientation": "landscape"
}
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "screens": [
- {
- "id": 0
}
], - "description": "string",
- "orientation": "landscape"
}
}Partial update — only include the fields you want to change.
| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string <= 255 characters |
{- "title": "string",
- "description": "string"
}{- "status": "success"
}The playlist of the main zone of the group's layout. A layout's other zones are read and written through /screen_groups/{id}/zones/{zoneId}/playlist.
| id required | integer |
{- "status": "success",
- "data": {
- "shufflePlay": true,
- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "items": [
- {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}
}Replaces the entire playlist. All member screens will receive the updated playlist.
| id required | integer |
| defaultTransition | string or null |
| defaultTransitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| enableImageTransitions | boolean |
| enableWebappTransitions | boolean |
| shufflePlay | boolean |
required | Array of objects <= 100 items At most 100 items, counting what the playlist plays: a standalone playlist item counts for every item its standalone playlist plays. |
{- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "shufflePlay": true,
- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "sequenceNumber": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}{- "status": "success"
}Adds one or more items to a screen group's existing playlist without replacing it. All member screens will receive the updated playlist. The playlist may then play at most 100 items, a standalone playlist item counting for every item it plays (PLAYLIST_LIMIT_EXCEEDED).
| id required | integer |
required | Array of objects [ 1 .. 50 ] items |
| position required | string Enum: "start" "end" Where to insert the items in the playlist |
{- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "scheduleEnabled": true,
- "periodicScheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "monStart": "09:00",
- "monEnd": "17:00",
- "tueStart": "09:00",
- "tueEnd": "17:00",
- "wedStart": "09:00",
- "wedEnd": "17:00",
- "thuStart": "09:00",
- "thuEnd": "17:00",
- "friStart": "09:00",
- "friEnd": "17:00",
- "satStart": "09:00",
- "satEnd": "17:00",
- "sunStart": "09:00",
- "sunEnd": "17:00"
}
], - "position": "start"
}{- "status": "success"
}Partially updates a single item on a screen group's playlist. Only the fields included in the request body are changed; omitted fields keep their current values. All member screens will receive the updated playlist. A day's start and end times (monStart/monEnd etc.) must be sent together; send both as null to clear that day's window.
mediafileId, webAppId, standalonePlaylistId and sequenceNumber cannot be changed here; to swap content or reorder, use PUT /screen_groups/{id}/playlist.
A standalone playlist item has only its schedule to change: displayDuration, transition or transitionSpeedLabel sent for one is refused with VALIDATION_ERROR.
| id required | integer |
| itemId required | integer ID of the playlist item to update |
| displayDuration | integer [ 0 .. 9999999 ] |
| transition | string or null |
| transitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| scheduleEnabled | boolean |
| periodicScheduleEnabled | boolean |
| scheduleStartDate | string or null <date-time> |
| scheduleEndDate | string or null <date-time> |
| scheduleRrule | string or null iCal RRULE for recurring schedule, in a layout the CMS writes: FREQ=DAILY; FREQ=WEEKLY with or without BYDAY; FREQ=MONTHLY with BYMONTHDAY, or with BYSETPOS and optionally BYDAY; FREQ=YEARLY with BYMONTH and either BYMONTHDAY, or BYSETPOS and optionally BYDAY. Any of them may add INTERVAL (up to 520) and COUNT or UNTIL, not both. BYMONTH, BYMONTHDAY and BYSETPOS take one value, BYDAY takes weekdays without a position (MO,WE, not 1MO), and each part is given once. Anything else, BYHOUR and BYMINUTE among it, is refused with VALIDATION_ERROR. |
| monStart | string or null Monday start time (HH:mm). |
| monEnd | string or null Monday end time (HH:mm). |
| tueStart | string or null Tuesday start time (HH:mm). |
| tueEnd | string or null Tuesday end time (HH:mm). |
| wedStart | string or null Wednesday start time (HH:mm). |
| wedEnd | string or null Wednesday end time (HH:mm). |
| thuStart | string or null Thursday start time (HH:mm). |
| thuEnd | string or null Thursday end time (HH:mm). |
| friStart | string or null Friday start time (HH:mm). |
| friEnd | string or null Friday end time (HH:mm). |
| satStart | string or null Saturday start time (HH:mm). |
| satEnd | string or null Saturday end time (HH:mm). |
| sunStart | string or null Sunday start time (HH:mm). |
| sunEnd | string or null Sunday end time (HH:mm). |
{- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "periodicScheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "monStart": "09:00",
- "monEnd": "17:00",
- "tueStart": "09:00",
- "tueEnd": "17:00",
- "wedStart": "09:00",
- "wedEnd": "17:00",
- "thuStart": "09:00",
- "thuEnd": "17:00",
- "friStart": "09:00",
- "friEnd": "17:00",
- "satStart": "09:00",
- "satEnd": "17:00",
- "sunStart": "09:00",
- "sunEnd": "17:00"
}{- "status": "success",
- "data": {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
}Returns the screens that belong to this screen group.
| id required | integer |
{- "status": "success",
- "data": [
- {
- "id": 0,
- "title": "string",
- "description": "string",
- "orientation": "landscape",
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "heartbeatTime": "2019-08-24T14:15:22Z",
- "softwareVersionCode": 0,
- "screenGroupId": 0,
- "popEnabled": true,
- "demo": true,
- "screenTags": [
- {
- "name": "string"
}
]
}
]
}Sets which screens belong to this group. Pass an array of screen IDs. Screens not in the array will be removed from the group; an empty array removes every screen. IDs of screens outside the workspace are ignored.
| id required | integer |
| screens required | Array of integers <= 100 items Array of screen IDs to assign to this group |
{- "screens": [
- 0
]
}{- "status": "success"
}The zones the screen group shows, the main zone first, and what the layout was made from. Every member screen shows it.
| id required | integer |
{- "status": "success",
- "data": {
- "preset": "main_sidebar",
- "layoutId": 0,
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent",
- "layoutZoneId": 0
}
]
}
}Replaces the screen group's layout with a preset or with one of the workspace's layouts. Send exactly one of preset and layoutId. The response is the new layout, with the ID of each zone.
The main zone and its playlist are kept. Another zone keeps its playlist only when the new layout has a zone to match it (the same zone of the same layout, or else a zone with the same name); zones with no match are deleted with their playlists, and new zones start empty. Apply full_screen to go back to a single zone.
| id required | integer |
| preset | string <= 32 characters Key of a preset from |
| layoutId | integer ID of a layout from |
{- "preset": "main_sidebar"
}{- "status": "success",
- "data": {
- "preset": "main_sidebar",
- "layoutId": 0,
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent",
- "layoutZoneId": 0
}
]
}
}The playlist of one zone of the screen group's layout. Zone IDs come from GET /screen_groups/{id}/layout. For the main zone this is the same playlist as GET /screen_groups/{id}/playlist.
| id required | integer |
| zoneId required | integer ID of a zone of the screen's or screen group's layout, from its |
{- "status": "success",
- "data": {
- "shufflePlay": true,
- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "items": [
- {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}
}Replaces the entire playlist of one zone. Send all items — existing items not included will be removed. Zones other than the main zone take images and web apps only; a standalone playlist item goes in the main zone only.
| id required | integer |
| zoneId required | integer ID of a zone of the screen's or screen group's layout, from its |
| defaultTransition | string or null |
| defaultTransitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| enableImageTransitions | boolean |
| enableWebappTransitions | boolean |
| shufflePlay | boolean |
required | Array of objects <= 100 items At most 100 items, counting what the playlist plays: a standalone playlist item counts for every item its standalone playlist plays. |
{- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "shufflePlay": true,
- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "sequenceNumber": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}{- "status": "success"
}A standalone playlist is a playlist of its own that screens and screen groups play as one
item of their playlist. A change to it reaches every screen playing it. GET /standalone_playlists lists them, with the ID a playlist item names; they are made and
changed here or in the AbleSign CMS.
Its own playlist (/standalone_playlists/{id}/playlist) takes media files, web apps
and other standalone playlists, as a screen's does.
As a playlist item. An item with a standalonePlaylistId, in place of a mediafileId
or webAppId, plays every item of that standalone playlist, in its order and with its
transitions. So it has no displayDuration or transition of its own; it has a schedule
like any item. It can only be in the playlist of a layout's main zone
(SUB_PLAYLIST_NOT_ALLOWED elsewhere), and the standalone playlist must be in the same
workspace: the ID of one in another workspace is dropped, as a media file's is.
The workspace's standalone playlists, to find the ID a playlist item names.
| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" Sort order |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "description": "string",
- "thumbnailURL": "string",
- "itemCount": 0,
- "totalDuration": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Makes an empty standalone playlist in the workspace; save its items with PUT /standalone_playlists/{id}/playlist. An account has at most 500 (RESOURCE_LIMIT_REACHED).
| title required | string <= 255 characters |
| description | string or null <= 255 characters |
{- "title": "string",
- "description": "string"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "thumbnailURL": "string",
- "itemCount": 0,
- "totalDuration": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "thumbnailURL": "string",
- "itemCount": 0,
- "totalDuration": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}Partial update of its title and description; a field left out keeps its value, and a null description clears it. Its items are saved with PUT /standalone_playlists/{id}/playlist.
| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string or null <= 255 characters |
{- "title": "string",
- "description": "string"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "thumbnailURL": "string",
- "itemCount": 0,
- "totalDuration": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}Deletes it and takes it out of every playlist that plays it, as deleting a media file does; the screens playing those playlists are updated at once.
| id required | integer |
{- "status": "error",
- "code": "NOT_FOUND",
- "message": "The requested resource was not found"
}Its items and playlist settings, in the shape of a screen's playlist. An item may be another standalone playlist.
| id required | integer |
{- "status": "success",
- "data": {
- "shufflePlay": true,
- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "items": [
- {
- "id": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "sequenceNumber": 0,
- "displayDuration": 0,
- "transition": "string",
- "transitionSpeedLabel": "string",
- "title": "string",
- "thumbnailURL": "string",
- "fileType": "string",
- "orientation": "string",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}
}Replaces its entire playlist, the same body as a screen's. Every screen and screen group playing it receives the change.
It cannot hold itself (SUB_PLAYLIST_IS_ITSELF) or a standalone playlist that holds it (SUB_PLAYLIST_CONTAINS_HOST), and standalone playlists nest at most 3 deep under a screen's playlist (SUB_PLAYLIST_TOO_DEEP). A save that would make a playlist playing it play more than 100 items is refused (HOST_PLAYLIST_LIMIT_EXCEEDED).
| id required | integer |
| defaultTransition | string or null |
| defaultTransitionSpeedLabel | string or null Enum: "very_slow" "slow" "medium" "fast" "very_fast" |
| enableImageTransitions | boolean |
| enableWebappTransitions | boolean |
| shufflePlay | boolean |
required | Array of objects <= 100 items At most 100 items, counting what the playlist plays: a standalone playlist item counts for every item its standalone playlist plays. |
{- "defaultTransition": "string",
- "defaultTransitionSpeedLabel": "very_slow",
- "enableImageTransitions": true,
- "enableWebappTransitions": true,
- "shufflePlay": true,
- "items": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "standalonePlaylistId": 0,
- "displayDuration": 0,
- "sequenceNumber": 0,
- "transition": "string",
- "transitionSpeedLabel": "very_slow",
- "scheduleEnabled": true,
- "scheduleStartDate": "2019-08-24T14:15:22Z",
- "scheduleEndDate": "2019-08-24T14:15:22Z",
- "scheduleRrule": "string",
- "periodicScheduleEnabled": true,
- "monStart": "09:00:00",
- "monEnd": "17:00:00",
- "tueStart": "09:00:00",
- "tueEnd": "17:00:00",
- "wedStart": "09:00:00",
- "wedEnd": "17:00:00",
- "thuStart": "09:00:00",
- "thuEnd": "17:00:00",
- "friStart": "09:00:00",
- "friEnd": "17:00:00",
- "satStart": "09:00:00",
- "satEnd": "17:00:00",
- "sunStart": "09:00:00",
- "sunEnd": "17:00:00"
}
]
}{- "status": "success"
}A layout divides the display into zones, each playing its own playlist. Every screen and
screen group has a layout; until you change it, that is full_screen, one zone covering
the display.
One zone is the main zone. Its playlist is the one /screens/{id}/playlist and
/screen_groups/{id}/playlist read and write, so an integration that does not use zones
is unaffected. The other zones play images and web apps; video is refused there
(ZONE_CONTENT_NOT_ALLOWED).
A zone's x, y, width and height are percentages of the screen as it is viewed
(after rotation), measured from the top left. Zones may overlap; the one with the higher
zIndex is drawn on top.
A layout is made from a preset (GET /layout_presets) or from one of the layouts
created in your workspace in the AbleSign CMS (GET /layouts). Layouts are designed in
the CMS; the API reads them and applies them.
Typical flow
PUT /screens/{id}/layout with { "preset": "main_sidebar" } or { "layoutId": 12 }.
The response lists the zones with their IDs.PUT /screens/{id}/zones/{zoneId}/playlist for each zone. The main zone's playlist can
also be written with PUT /screens/{id}/playlist.The same routes exist under /screen_groups/{id}. A screen in a screen group shows the
group's layout: read it through either, change it through the group.
Changing a layout keeps the main zone and its playlist. Another zone keeps its playlist only when the new layout has a zone to match it: the same zone of the same layout, or else a zone with the same name. Zones with no match are deleted with their playlists. When a layout is edited in the CMS, every screen and group using it follows.
Not every player shows zones: an older player app, or a device that cannot, plays the
main zone full screen. GET /screens/{id} reports this as capabilities.zones.
The ready-made layouts every account can use. Apply one by its key.
{- "status": "success",
- "data": [
- {
- "key": "main_sidebar",
- "name": "Main + sidebar",
- "orientation": "landscape",
- "zones": [
- {
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent"
}
]
}
]
}The layouts created in the active workspace in the AbleSign CMS, each with its zones. The list is not paginated. Apply one by its id.
{- "status": "success",
- "data": [
- {
- "id": 0,
- "name": "string",
- "orientation": "landscape",
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent"
}
], - "createdAt": "2019-08-24T14:15:22Z"
}
]
}{- "status": "success",
- "data": {
- "id": 0,
- "name": "string",
- "orientation": "landscape",
- "zones": [
- {
- "id": 0,
- "primary": true,
- "name": "string",
- "x": 0,
- "y": 0,
- "width": 0,
- "height": 0,
- "zIndex": 0,
- "fit": "CenterCrop",
- "background": "transparent"
}
], - "createdAt": "2019-08-24T14:15:22Z"
}
}| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" "start_date_asc" "start_date_desc" "expiry_date_asc" "expiry_date_desc" Sort order |
| folderId | integer Filter by folder ID |
| formats | string Comma-separated format filter (image, video). Case-insensitive. |
| orientations | string Comma-separated orientation filter (landscape, portrait) |
| tags | string <= 255 characters Comma-separated tag filter |
| fromDate | string <date-time> Example: fromDate=2026-11-01T00:00:00Z Filter to files created at or after this time (ISO 8601; a time without an offset is UTC, a date alone is midnight UTC) |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "originalFilename": "string",
- "fileType": "image",
- "fileSize": 0,
- "orientation": "landscape",
- "duration": 0,
- "width": 0,
- "height": 0,
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "demo": true,
- "folderId": 0,
- "tags": [
- {
- "name": "string"
}
]
}
]
}Returns file details including a signed access URL for downloading the file.
| id required | integer |
{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "originalFilename": "string",
- "fileType": "image",
- "fileSize": 0,
- "orientation": "landscape",
- "duration": 0,
- "width": 0,
- "height": 0,
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "demo": true,
- "folderId": 0,
- "tags": [
- {
- "name": "string"
}
], - "description": "string",
- "fileBitrate": 0,
- "accessUrl": "string"
}
}Partial update — only include the fields you want to change.
| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string <= 255 characters |
| startDate | string or null <date-time> Schedule start date (file won't appear in playlists before this date) |
| expirationDate | string or null <date-time> Expiration date (file will be removed from playlists after this date) |
| tags | Array of strings <= 20 items Tags to assign to this file (replaces existing tags) |
{- "title": "string",
- "description": "string",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "tags": [
- "string"
]
}{- "status": "success"
}Step 1 of the upload flow. Returns a signed S3 URL to upload the file to.
Upload flow:
init_upload with the filename, MIME type, and file sizeurl using an HTTP PUT requestfinish_upload with the uploadId to complete the processThe url must be used within 6 hours, and the PUT must send exactly size bytes
(its Content-Length); S3 refuses any other length with a 403.
| filename required | string Original filename (e.g. "photo.jpg") |
| mimeType required | string MIME type (e.g. "image/jpeg", "video/mp4") |
| size required | integer >= 1 File size in bytes |
| folderId | integer Optional folder ID to upload into |
{- "filename": "string",
- "mimeType": "string",
- "size": 1,
- "folderId": 0
}{- "status": "success",
- "data": {
- "url": "string",
- "uploadId": 0
}
}Step 3 of the upload flow. Call this after uploading the file to S3. The server will process the file (generate thumbnail, extract metadata) and create the media file record.
| uploadId required | integer The uploadId returned from init_upload |
{- "uploadId": 0
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "originalFilename": "string",
- "fileType": "image",
- "fileSize": 0,
- "orientation": "landscape",
- "duration": 0,
- "width": 0,
- "height": 0,
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "demo": true,
- "folderId": 0,
- "tags": [
- {
- "name": "string"
}
], - "description": "string",
- "fileBitrate": 0,
- "accessUrl": "string"
}
}Step 1 of the replace flow. Replaces the content of an existing media file while keeping the same ID. The replacement file must be the same type (e.g. image for image, video for video).
Replace flow:
init_replace_upload with the filename, MIME type, size, and the ID of the file to replaceurl using an HTTP PUT request, within 6 hours and
with exactly size bytes; S3 refuses any other length with a 403finish_replace_upload with the uploadId to complete the process| filename required | string Original filename of the replacement file |
| mimeType required | string MIME type (must match the existing file's type) |
| size required | integer >= 1 File size in bytes |
| mediafileId required | integer ID of the existing media file to replace |
{- "filename": "string",
- "mimeType": "string",
- "size": 1,
- "mediafileId": 0
}{- "status": "success",
- "data": {
- "url": "string",
- "uploadId": 0
}
}Step 3 of the replace flow. Call this after uploading the replacement file to S3. The server will process the new file and update the existing media file record.
| uploadId required | integer The uploadId returned from init_replace_upload |
{- "uploadId": 0
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "originalFilename": "string",
- "fileType": "image",
- "fileSize": 0,
- "orientation": "landscape",
- "duration": 0,
- "width": 0,
- "height": 0,
- "thumbnailURL": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "demo": true,
- "folderId": 0,
- "tags": [
- {
- "name": "string"
}
], - "description": "string",
- "fileBitrate": 0,
- "accessUrl": "string"
}
}| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" Sort order |
| folderId | integer Filter by parent folder ID |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "parentFolderId": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}| title required | string <= 255 characters |
| parentFolderId | integer or null ID of the parent folder (null for root level) |
{- "title": "string",
- "parentFolderId": 0
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "parentFolderId": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}| id required | integer |
| title | string [ 1 .. 255 ] characters |
{- "title": "string"
}{- "status": "success"
}| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
| title | string <= 255 characters Filter by title (partial match) |
| sortBy | string Enum: "title_asc" "title_desc" "creation_date_asc" "creation_date_desc" "start_date_asc" "start_date_desc" "expiry_date_asc" "expiry_date_desc" Sort order |
| tags | string <= 255 characters Comma-separated tag filter |
| fromDate | string <date-time> Example: fromDate=2026-11-01T00:00:00Z Filter to web apps created at or after this time (ISO 8601; a time without an offset is UTC, a date alone is midnight UTC) |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "thumbnailPending": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "tags": [
- {
- "name": "string"
}
]
}
]
}Create a web app from a URL or HTML content. You must provide either url or html.
| title required | string <= 255 characters |
| description | string <= 255 characters |
| url | string <= 2048 characters URL of the website to display. Required if html is not provided. An address without
a scheme gets |
| html | string <= 5000000 characters Raw HTML content. Required if url is not provided. |
{- "title": "string",
- "description": "string",
- "url": "string",
- "html": "string"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "thumbnailPending": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "tags": [
- {
- "name": "string"
}
], - "description": "string",
- "url": "string",
- "zoom": 67,
- "accessUrl": "string"
}
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "thumbnailURL": "string",
- "thumbnailPending": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "tags": [
- {
- "name": "string"
}
], - "description": "string",
- "url": "string",
- "zoom": 67,
- "accessUrl": "string"
}
}Partial update — only include the fields you want to change.
| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string <= 255 characters |
| url | string <= 2048 characters URL of the website, under the same rules as on create ( |
| startDate | string or null <date-time> Schedule start date (web app won't appear in playlists before this date) |
| expirationDate | string or null <date-time> Expiration date (web app will be removed from playlists after this date) |
| zoom | integer Enum: 67 75 80 90 100 125 150 175 200 225 Zoom level applied when rendering the web page (default: 100) |
| tags | Array of strings <= 20 items Tags to assign to this web app (replaces existing tags) |
{- "title": "string",
- "description": "string",
- "url": "string",
- "startDate": "2019-08-24T14:15:22Z",
- "expirationDate": "2019-08-24T14:15:22Z",
- "zoom": 67,
- "tags": [
- "string"
]
}{- "status": "success"
}Returns all workspaces in your organization. Use the id of a workspace in the Workspace-Id header on other requests to operate on that workspace.
{- "status": "success",
- "data": [
- {
- "id": 0,
- "title": "string",
- "description": "string",
- "color": "#FF8800",
- "isDefault": true,
- "userCount": 0,
- "screenCount": 0,
- "mediafileCount": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}| title required | string <= 255 characters |
| description | string or null <= 255 characters |
| color | string or null^#[0-9A-Fa-f]{6}$ Hex color code (e.g. "#FF8800") |
{- "title": "string",
- "description": "string",
- "color": "string"
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "color": "#FF8800",
- "isDefault": true,
- "userCount": 0,
- "screenCount": 0,
- "mediafileCount": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}{- "status": "success",
- "data": {
- "id": 0,
- "title": "string",
- "description": "string",
- "color": "#FF8800",
- "isDefault": true,
- "userCount": 0,
- "screenCount": 0,
- "mediafileCount": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
}| id required | integer |
| title | string [ 1 .. 255 ] characters |
| description | string or null <= 255 characters |
| color | string or null^#[0-9A-Fa-f]{6}$ |
{- "title": "string",
- "description": "string",
- "color": "string"
}{- "status": "success"
}Deletes a workspace. The workspace must be empty — it cannot be the default workspace, contain screens, media files, or web apps, or have any users assigned other than the account owner.
| id required | integer |
{- "status": "error",
- "code": "NOT_FOUND",
- "message": "The requested resource was not found"
}{- "status": "success",
- "data": [
- {
- "id": 0,
- "role": "string",
- "isAccountOwner": true,
- "disabled": true,
- "pendingInviteAccept": true,
- "profile": {
- "firstName": "string",
- "lastName": "string",
- "email": "string",
- "avatarFile": "string",
- "avatarURL": "string"
}, - "workspaces": [
- {
- "id": 0,
- "title": "string",
- "role": "string",
- "viewContent": true,
- "manageContent": true,
- "viewWebsites": true,
- "manageWebsites": true,
- "viewScreens": true,
- "manageScreens": true,
- "managePlaylists": true,
- "administrator": true,
- "manageBilling": true
}
]
}
]
}Returns the raw records reported by screens, oldest first. Each record covers one reporting period on one screen for one asset (a media file or a web app) and carries the number of plays and the total time on screen in that period.
Only screens with proof of play enabled report. A date range is required and may span at most 92 days. Dates are ISO 8601 in UTC; a date-only value means midnight UTC. Records are kept for a limited period, so export regularly if you need a long-term history.
| fromDate required | string <date-time> Include records whose period starts at or after this instant |
| toDate required | string <date-time> Include records whose period ends at or before this instant (at most 92 days after fromDate) |
| screenId | integer |
| mediafileId | integer Only records for this media file (cannot be combined with webAppId) |
| webAppId | integer Only records for this web app (cannot be combined with mediafileId) |
| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "id": 0,
- "screenId": 0,
- "mediafileId": 0,
- "webAppId": 0,
- "periodStart": "2019-08-24T14:15:22Z",
- "periodEnd": "2019-08-24T14:15:22Z",
- "playCount": 0,
- "totalDuration": 0,
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Returns one row per asset (media file or web app) with the number of screens it played on,
the total plays and the total time on screen across the matching records. Assets that have
since been deleted are reported with deleted: true and a null assetName.
Dates are ISO 8601 in UTC and optional. Without a range the summary covers every record still retained.
| fromDate | string <date-time> |
| toDate | string <date-time> |
| screenId | integer |
| title | string Only assets whose name contains this text |
| tags | string Comma-separated content tag names; matches assets with any of them |
| screenTags | string Comma-separated screen tag names; only counts plays on screens with any of them |
| sources | string Comma-separated subset of |
| sortField | string Default: "totalPlays" Enum: "assetName" "assetType" "screenCount" "totalPlays" "totalDuration" |
| sortDirection | string Default: "desc" Enum: "asc" "desc" |
| limit | integer [ 1 .. 200 ] Default: 25 Number of items to return (max 200) |
| offset | integer >= 0 Default: 0 Number of items to skip |
{- "status": "success",
- "totalItems": 0,
- "limit": 0,
- "offset": 0,
- "data": [
- {
- "mediafileId": 0,
- "webAppId": 0,
- "assetName": "string",
- "assetType": "Image",
- "deleted": true,
- "screenCount": 0,
- "totalPlays": 0,
- "totalDuration": 0
}
]
}Returns one row per screen that played the given asset, most plays first. Exactly one of
mediafileId or webAppId is required. Screens that have since been deleted are returned
with deleted: true and a null screenName.
| mediafileId | integer |
| webAppId | integer |
| fromDate | string <date-time> |
| toDate | string <date-time> |
| screenTags | string Comma-separated screen tag names |
{- "status": "success",
- "data": [
- {
- "screenId": 0,
- "screenName": "string",
- "deleted": true,
- "playCount": 0,
- "totalDuration": 0
}
]
}