How to get started with the AbleSign API

The AbleSign API lets you manage your screens, content, and playlists programmatically. In this guide we’ll walk through a practical example: uploading an image file and adding it to a screen’s playlist using curl commands.

Authentication

All API requests require your API key passed as a Bearer token in the Authorization header:

Authorization: Bearer ak_your_api_key_here

Step 1: List your screens

First, let’s find the screen we want to add content to. This request lists all screens in your workspace:

curl -s \
  -H "Authorization: Bearer ak_your_api_key_here" \
  https://api.ablesign.tv/api/v1/screens

The response includes your screens with their IDs, titles, and other details:

{
  "status": "success",
  "data": [
    {
      "id": 613502,
      "title": "Demonstration screen",
      "orientation": "landscape",
      "heartbeatTime": "2026-04-09T10:30:00.000Z",
      ...
    }
  ],
  "totalItems": 1
}

Make a note of the screen id — you’ll need it in Step 4.

Step 2: Upload a file — initiate the upload

Uploading a file is a three-step process. First, tell the API about the file you want to upload:

curl -s -X POST \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-image.jpg",
    "mimeType": "image/jpeg",
    "size": 50000
  }' \
  https://api.ablesign.tv/api/v1/media_files/init_upload

The response contains a signed upload URL and an upload ID:

{
  "status": "success",
  "data": {
    "url": "https://ablesign-s3bucket.s3.eu-west-2.amazonaws.com/...",
    "uploadId": 1836223
  }
}

Step 3: Upload the file to the signed URL

Now upload your file directly to the signed URL using an HTTP PUT request. Replace the URL with the one you received in the previous step:

curl -X PUT \
  -H "Content-Type: image/jpeg" \
  --data-binary @my-image.jpg \
  "https://ablesign-s3bucket.s3.eu-west-2.amazonaws.com/..."

Step 4: Complete the upload

After the file has been uploaded to the signed URL, call the finish_upload endpoint with the upload ID. The server will process the file, generate a thumbnail, and create the media file record:

curl -s -X POST \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": 1836223}' \
  https://api.ablesign.tv/api/v1/media_files/finish_upload

The response contains the details of the newly created media file:

{
  "status": "success",
  "data": {
    "id": 2179100,
    "title": "my-image.jpg",
    "originalFilename": "my-image.jpg",
    "fileType": "image",
    "fileSize": 50000,
    "orientation": "landscape",
    "width": 1920,
    "height": 1080,
    ...
  }
}

Make a note of the file id — you’ll need it to add the file to a playlist.

Step 5: Set the screen’s playlist

Now set the screen’s playlist to include the uploaded file. This replaces the entire playlist, so include all items you want displayed. Replace the screen ID and media file ID with your own values:

curl -s -X PUT \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "mediafileId": 2179100,
        "displayDuration": 10,
        "sequenceNumber": 0
      }
    ],
    "shufflePlay": false
  }' \
  https://api.ablesign.tv/api/v1/screens/613502/playlist

The displayDuration is in seconds — this controls how long the image is shown before moving to the next item. For video files, the display duration is automatically set to the video’s length.

The sequenceNumber determines the order of items in the playlist, starting from 0.

Step 6: Verify the playlist

You can check the screen’s playlist to confirm the file was added:

curl -s \
  -H "Authorization: Bearer ak_your_api_key_here" \
  https://api.ablesign.tv/api/v1/screens/613502/playlist

The response shows the full playlist including the item you just added:

{
  "status": "success",
  "data": {
    "shufflePlay": false,
    "defaultTransition": null,
    "items": [
      {
        "id": 161900,
        "mediafileId": 2179100,
        "displayDuration": 10,
        "title": "my-image.jpg",
        "fileType": "image",
        ...
      }
    ]
  }
}

The screen will automatically download and display the new content within a few minutes.

Next steps

Now that you’ve uploaded a file and added it to a playlist, you can explore the full API documentation to learn about managing screen groups, web apps, folders, and more.

• Full API documentation