API docs by Redocly

AbleSign API (1.0.0)

Download OpenAPI specification:

AbleSign Support: support@ablesign.tv URL: https://www.ablesign.tv

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.

Authentication

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.

Workspaces

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.

Pagination

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.

Errors

Error responses follow a consistent format:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable description"
}

Error codes

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
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 limits

The API applies rate limits to protect the platform:

Operation Limits Scope
Save playlist 5/min, 20/hr Per screen or screen group
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 Per organization

When a rate limit is exceeded, the API returns a 429 status code with a RATE_LIMIT_EXCEEDED error code. Wait for the window to pass before retrying.

Screens

Manage screens and their playlists

List screens

Returns a paginated list of screens in the active workspace.

Authorizations:
BearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "totalItems": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    ]
}

Register a screen

Register a new screen using a pairing code displayed on the device.

Authorizations:
BearerAuth
Request Body schema: application/json
required
registrationCode
required
string = 6 characters

The 6-character code displayed on the device

title
required
string <= 255 characters
description
string <= 255 characters
orientation
required
string
Enum: "landscape" "portrait" "reverse_portrait" "reverse_landscape"

Responses

Request samples

Content type
application/json
{
  • "registrationCode": "string",
  • "title": "string",
  • "description": "string",
  • "orientation": "landscape"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get screen details

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a screen

Partial update — only include the fields you want to change.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
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)

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

syncLeaderScreenId
integer or null

ID of the leader screen (required when syncRole is follower)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "orientation": "landscape",
  • "fitItem": "CenterCrop",
  • "timezone": "string",
  • "screenTags": [
    ],
  • "syncEnabled": true,
  • "syncRole": "leader",
  • "syncLeaderScreenId": 0
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete a screen

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "code": "NOT_FOUND",
  • "message": "The requested resource was not found"
}

Get screen playlist

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Save screen playlist

Replaces the entire playlist. Send all items — existing items not included will be removed.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
defaultTransition
string or null
defaultTransitionSpeedLabel
string or null
Enum: "very_slow" "slow" "medium" "fast" "very_fast"
enableImageTransitions
boolean
enableWebappTransitions
boolean
shufflePlay
boolean
Array of objects <= 100 items

Responses

Request samples

Content type
application/json
{
  • "defaultTransition": "string",
  • "defaultTransitionSpeedLabel": "very_slow",
  • "enableImageTransitions": true,
  • "enableWebappTransitions": true,
  • "shufflePlay": true,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Add items to playlist

Adds one or more items to a screen's existing playlist without replacing it.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
required
Array of objects [ 1 .. 50 ] items
position
required
string
Enum: "start" "end"

Where to insert the items in the playlist

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "position": "start"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Screen Groups

Manage screen groups and their playlists

List screen groups

Authorizations:
BearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "totalItems": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    ]
}

Create a screen group

Authorizations:
BearerAuth
Request Body schema: application/json
required
title
required
string <= 255 characters
description
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get screen group details

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a screen group

Partial update — only include the fields you want to change.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
title
string [ 1 .. 255 ] characters
description
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete a screen group

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "code": "NOT_FOUND",
  • "message": "The requested resource was not found"
}

Get screen group playlist

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Save screen group playlist

Replaces the entire playlist. All member screens will receive the updated playlist.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
defaultTransition
string or null
defaultTransitionSpeedLabel
string or null
Enum: "very_slow" "slow" "medium" "fast" "very_fast"
enableImageTransitions
boolean
enableWebappTransitions
boolean
shufflePlay
boolean
Array of objects <= 100 items

Responses

Request samples

Content type
application/json
{
  • "defaultTransition": "string",
  • "defaultTransitionSpeedLabel": "very_slow",
  • "enableImageTransitions": true,
  • "enableWebappTransitions": true,
  • "shufflePlay": true,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Get member screens

Returns the screens that belong to this screen group.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ]
}

Set screen group members

Sets which screens belong to this group. Pass an array of screen IDs. Screens not in the array will be removed from the group.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
screens
required
Array of integers <= 100 items

Array of screen IDs to assign to this group

Responses

Request samples

Content type
application/json
{
  • "screens": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Media Files

Upload and manage media files (images, videos, PDFs)

List media files

Authorizations:
BearerAuth
query Parameters
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>

Filter to files created on or after this date

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "totalItems": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    ]
}

Get media file details

Returns file details including a signed access URL for downloading the file.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update media file metadata

Partial update — only include the fields you want to change.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
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)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete a media file

Deletes the file and removes it from all playlists.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "code": "NOT_FOUND",
  • "message": "The requested resource was not found"
}

Initiate a file upload

Step 1 of the upload flow. Returns a signed S3 URL to upload the file to.

Upload flow:

  1. Call init_upload with the filename, MIME type, and file size
  2. Upload the file to the returned url using an HTTP PUT request
  3. Call finish_upload with the uploadId to complete the process
Authorizations:
BearerAuth
Request Body schema: application/json
required
filename
required
string

Original filename (e.g. "photo.jpg")

mimeType
required
string

MIME type (e.g. "image/jpeg", "video/mp4")

size
required
integer

File size in bytes

folderId
integer

Optional folder ID to upload into

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "mimeType": "string",
  • "size": 0,
  • "folderId": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Complete a file upload

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.

Authorizations:
BearerAuth
Request Body schema: application/json
required
uploadId
required
integer

The uploadId returned from init_upload

Responses

Request samples

Content type
application/json
{
  • "uploadId": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Initiate a file replacement

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:

  1. Call init_replace_upload with the filename, MIME type, size, and the ID of the file to replace
  2. Upload the new file to the returned url using an HTTP PUT request
  3. Call finish_replace_upload with the uploadId to complete the process
Authorizations:
BearerAuth
Request Body schema: application/json
required
filename
required
string

Original filename of the replacement file

mimeType
required
string

MIME type (must match the existing file's type)

size
required
integer

File size in bytes

mediafileId
required
integer

ID of the existing media file to replace

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "mimeType": "string",
  • "size": 0,
  • "mediafileId": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Complete a file replacement

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.

Authorizations:
BearerAuth
Request Body schema: application/json
required
uploadId
required
integer

The uploadId returned from init_replace_upload

Responses

Request samples

Content type
application/json
{
  • "uploadId": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Folders

Organize media files into folders

List folders

Authorizations:
BearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "totalItems": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    ]
}

Create a folder

Authorizations:
BearerAuth
Request Body schema: application/json
required
title
required
string <= 255 characters
parentFolderId
integer or null

ID of the parent folder (null for root level)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "parentFolderId": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get a folder

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a folder

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
title
string [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete a folder

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "code": "NOT_FOUND",
  • "message": "The requested resource was not found"
}

Web Apps

Create and manage web apps (websites, HTML content)

List web apps

Authorizations:
BearerAuth
query Parameters
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>

Filter to web apps created on or after this date

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "totalItems": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    ]
}

Create a web app

Create a web app from a URL or HTML content. You must provide either url or html.

Authorizations:
BearerAuth
Request Body schema: application/json
required
title
required
string <= 255 characters
description
string <= 255 characters
url
string <uri> <= 2048 characters

URL of the website to display. Required if html is not provided.

html
string <= 5000000 characters

Raw HTML content. Required if url is not provided.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Get web app details

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Update a web app

Partial update — only include the fields you want to change.

Authorizations:
BearerAuth
path Parameters
id
required
integer
Request Body schema: application/json
required
title
string [ 1 .. 255 ] characters
description
string <= 255 characters
url
string <uri> <= 2048 characters

URL of the website

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: 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)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "url": "http://example.com",
  • "startDate": "2019-08-24T14:15:22Z",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "zoom": 75,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Delete a web app

Deletes the web app and removes it from all playlists.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": "error",
  • "code": "NOT_FOUND",
  • "message": "The requested resource was not found"
}