Skip to main content
API docs by Redocly

signageOS REST API (0.0.0)

Download OpenAPI specification:Download

Introduction

signageOS helps any developer to build apps for displays and remotely manage large networks of displays in a standardized way. No matter what display you are using, all APIs work across all of them.

Read more here:


About REST API

The signageOS REST API brings extra features for signageOS users with out-of-the-box device management, monitoring, and maintenance service provided by signageOS. With an existing, scalable, and flexible solution you can easily integrate advanced features into your CMS via standardized REST API. No need to re-invent the wheel again.

All APIs are standardized and available across all supported devices.

To use REST API, you need an Organization on Device Plan 1.0, 2.0 or 3.0. REST API does not work on free Open Device Plan.


List of REST API Domains

Domain Description
Device Configure the device, set timers, brightness, volume, RM server url, update the Core App, update firmware and much more, get device uptime, temperature, outages, content status or custom logs.
Applet Way to create your own Applets and its versions over API instead of Box.
Timing Timing REST API helps you schedule Applets (your HTML player) on the devices.
Organizations Organization/User REST API helps you to manage your account and create/delete organizations and retrieve security tokens.
Account Manage or delete security account tokens.
Firmware Manage firmware versions on supported devices.
Emulator Create emulators, test your environment or simply manage them.
Policy Manage policies with various settings, set up new policies or configure exiting policies and assign them to devices.
Tag Manage tags.
Alert (Coming soon) Manage device alerts and get informed about anomalies on production devices.
Location (Coming soon) Managing and filtering devices by assigned locations.
Bulk Provisioning Register your devices and automate the deployment

REST API Authentication

For REST API your application needs to be authenticated using request Header: X-Auth which is different for every single organization (end company owning/using devices). There is a possibility to create a sub-organization for any of your customers in signageOS Box.

  1. Go to Organizations section in signageOS Box and generate your token_id & token_secret.
  2. Use it as X-Auth header separated by colon - __TOKEN_ID:__TOKEN_SECRET__.
# X-Auth = client_id:client_secret
curl -XGET -H "X-Auth: 87e376c08d16XXXXb796294744:5ef829c933aXXXX710f5388a27fee" \
  https://api.signageos.io/v1/device

If X-Auth token is invalid or generated token does not have permissions in organization you will receive 403 Forbidden response.


REST API Request Quota

signageOS REST API automatically applies quotas on REST requests. The quota is counted per IP address of the Request origin.

The quota is set to 200 requests per second for instant response and 500 queued requests with a slightly delayed response based on request type and performance.

If you reach the quota API returns 429 Too Many Requests response.

It is important to note that after creating a Company through REST API, the default Device plan is set to 3.0. This can be changed from within SignageOS Box under your Company profile.


Pagination

There is enforced maximum length of data that can be returned in a single response. If there's more data available, than the limit allows, data will be returned in multiple pages. Cursor based pagination will be used. https://jsonapi.org/profiles/ethanresnick/cursor-pagination/#auto-id-query-parameters Parameter limit can be used for setting the page size. Setting the limit over the max allowed limit will result in error. Beware not to change the limit in the middle of the process of fetching pages. If a different limit is specified, process needs to be started over from the first page. Request without additional parameters will return the first page. If there are more data available, the response will contain a header "Link" that will contain the link to the next page, e.g. <https://api.signageos.io/v1/device?until=2021-11-01T00%3A33%3A38.918Z>; rel="next". Then by performing another request with the link next page will be returned. Each response will contain a link to the next page until there are no more data left.


Url structure

List parameters

There are two ways lists could be encoded:

  • ... <LIST_PARAM_NAME>=<VALUE_0>&<LIST_PARAM_NAME>=<VALUE_1>&<LIST_PARAM_NAME>=<VALUE_2> ...
  • ... <LIST_PARAM_NAME>=<VALUE_0>,<VALUE_1>,<VALUE_2>...

For example, list with values uid1, uid2, uid3, encoded in URL as parameter deviceUid will look like this: deviceUid=uid1&deviceUid=uid2&deviceUid=uid3 or deviceUid=uid1,uid2,uid3

In the case of comma-separated values, any string value containing a comma should be escaped.

Asynchronous REST API Requests

While some of API endpoints can be “fire and forget”, i.e. there is no need to report back to the client, for example, when initiating a bulk actions. For others, the client may need a response, but can't get it in the original request because of the long processing time, i.e. in case of firmware upgrade request or Applet operations. In those cases, we have to do a "pre-flight" check and connect directly with device to execute the action, which can be a time-consuming process, often better performed asynchronously. For these asynchronous operations (typically all /device/xxxx endpoints) we adopted a polling strategy. Clients can retrieve the results of asynchronous requests by polling a special endpoint that will return the result of the request, once it's available.

Standard Flow Example

  1. The client sends the PUT request - set brightness to 100% - to the server to begin the operation. 1. The server accepts the request, confirming by 200 OK message. 1. The asynchronous process begins on the server side, triggering desired function - connecting to device, setting a brightness and confirming the value was set and accepted by the device. 1. Finally, the server finished the action by receiving a confirmation from the device - brightness successfully set to 100%. During this process, the client polls the GET URI of the brightness endpoint. The server returns the status of the last request: json { "uid": "deed07d35fdxxx", "deviceUid": "e824fcd24a4fxxx", "createdAt": "2022-07-22T12:06:45.540Z", "succeededAt": "2022-07-22T12:06:55.850Z", "failedAt": null, "brightness1": 90, "brightness2": 40, "timeFrom1": "09:00:00", "timeFrom2": "20:00:00" } Status of the operation is available under succeededAt and failedAt keys. If the request succeeeded, succeededAt will be set. If it failed, failedAt will be set. If non of the two are set, it means that the request is still pending. Flow diagram of async requests

    Important consideration In the polling pattern, the client must decide how frequently to poll the URL and when to give up. One common choice is exponential backoff, which increases the interval between checks until a maximum interval is reached or the response (succeededAt/failedAt) is received.


Account

Create Account Security Token

Create security token for account by username/email/id and password.

query Parameters
identification
string
Example: identification={{username}}

Login username (required)

password
string
Example: password={{password}}

Login password (required)

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Body need to by in JSON

Responses

Delete All Account Security Tokens

Delete all security tokens from account by username/email/id and password.

query Parameters
identification
string
Example: identification={{username}}

Login username (required)

password
string
Example: password={{password}}

Login password (required)

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Delete One Account Security Token

Delete one security token from account by username/email/id and password and token itself.

path Parameters
token
required
string
Example: {{token}}
query Parameters
identification
string
Example: identification={{username}}

Login username (required)

password
string
Example: password={{password}}

Login password (required)

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Applet

The Applet is an HTML5/Javascript application that runs within the signageOS Core App. Applet can leverage the Applet JS API for easy access to the device native functions like saving files into internal memory and using accelerated video playback among others.

Get Applets

Get all applets of current organization

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create Applet

Create a new Applet that can be assigned to the device.

Body

Content-type: application/json or application/x-www-form-urlencoded

Field Type Required Description
name string required Your new Applet name, eg. Cool Applet

Assigning Applet to Device

Looking for a way how to set Applet to device? The endpoint you are looking for is called Timing.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "Applet Name"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Applet

Get one applet by appletUid. The UID can be found in list of all applets in signageOS Box.

Parameters

Field Type Required Description
appletUid string required Unique applet identification
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "uid": "bd74395949f7de6f143e59f00e8e351b8a01899873bb76be78",
  • "name": "Demo Applet",
  • "createdAt": "2017-05-24T08:58:56.994Z"
}

Delete Applet

Delete one Applet by appletUid. All assigned Timings on any device have to be deleted first.

Parameters

Field Type Required Description
appletUid string required Unique applet identification
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Create Applet Version

To create new Applet version you need just a new version of HTML (binary).

There is a better way, use signageOS CLI for creating multifile Applets

Parameters

Field Type Required Description
appletUid string required Unique Applet identification

Body

content-type: application/json or application/x-www-form-urlencoded

Field Type Required Description
binary string required HTML file
version string (semver) required Version of your Applet, e.g. 1.0.12
frontAppletVersion string (semver) required Version of Content Applet JS API
entryFile string optional Entry file name

Assigning Applet to Device

Looking for a way how to set Applet to device? The endpoint you are looking for is called Timing.

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "binary": "<html><h1>Hello world</h1></html>",
  • "version": "{{appletVersion}}",
  • "frontAppletVersion": "1.0.5"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Applet Versions

Get all Applet versions of the Applet by appletUid.

Several Applet versions make upgrade process and device operation a lot safer. This API call returns versions of selected Applet.

Parameters

Field Type Required Description
appletUid string required unique applet identification
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Applet Version

Get one specific Applet version of the Applet by appletUid and appletVersion

Parameters

Field Type Required Description
appletUid string required Unique applet identification
appletVersion string (semver) optional Version of your Applet, e.g. 1.0.12
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "appletUid": "bd74395949f7de6f143e59f00e8e351b8a01899873bb76be78",
  • "version": "0.0.1",
  • "createdAt": "2017-05-24T09:12:13.251Z",
  • "updatedAt": "2017-09-12T09:09:53.240Z",
  • "binary": null,
  • "frontAppletVersion": "1.0.3",
  • "publishedSince": null,
  • "deprecatedSince": null,
  • "builtSince": "2017-10-10T19:54:25.206Z"
}

Update Applet Version

Update existing Applet version of the Applet by appletUid and appletVersion.

To update any of your Applet version you need just new version of HTML (binary).

There is a better way, use signageOS CLI for creating multifile Applets

Parameters

Field Type Required Description
appletUid string required Unique Applet identification
appletVersion string (semver) optional Version of your Applet, e.g. 1.0.12

Body

content-type: application/json or application/x-www-form-urlencoded

Field Type Required Description
binary string required HTML file as string
frontAppletVersion string (semver) required Version of Content Applet JS API
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "binary": "<html><h1>Hello world</h1></html>",
  • "frontAppletVersion": "1.0.5"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Upload Applet Version Files

Upload file to applet version files by appletUid & appletVersion.

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

query Parameters
build
boolean

Do the build of applet version when file is uploaded. Accepted values '0', '1', 'true', 'false'.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
path
required
string

Path where will be file uploaded. Must be an absolute path.

hash
required
string

MD5 checksum of uploaded file

type
string

Content-Type (MIME type) of the uploaded file

Responses

Request samples

Content type
application/json
{
  • "path": "index.html",
  • "hash": "045e372a1eeafee2ce5580443c18a91d",
  • "type": "text/html"
}

Response samples

Content type
application/json
{
  • "upload": {
    },
  • "file": {}
}

Get Applet Version Files

Get file of applet version files by appletUid, appletVersion

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Get Applet Version File

Get file of applet version files by appletUid, appletVersion & appletFileName

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

appletFileName
required
string
Example: {{appletFileName}}

File name in Applet Version. It has to be relative path to applet root. It cannot start with slash /. It's forbidden to upload files inside node_modules directory.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Upload and Update Applet Version Files

Upload and update existing file to applet version files by appletUid , appletVersion & appletFileName

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

appletFileName
required
string
Example: {{appletFileName}}

File name in Applet Version. It has to be relative path to applet root. It cannot start with slash /. It's forbidden to upload files inside node_modules directory.

query Parameters
build
boolean

Do the build of applet version when file is uploaded. Accepted values '0', '1', 'true', 'false'.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
hash
required
string

MD5 checksum of uploaded file

type
string

Content-Type (MIME type) of the uploaded file

Responses

Request samples

Content type
application/json
{
  • "hash": "045e372a1eeafee2ce5580443c18a91d",
  • "type": "text/javascript"
}

Response samples

Content type
application/json
{
  • "upload": {
    },
  • "file": {}
}

Delete Applet Version File

Delete an existing file to applet version files by appletUid, appletVersion & appletFileName

path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

appletFileName
required
string
Example: {{appletFileName}}

File name in Applet Version. It has to be relative path to applet root. It cannot start with slash /. It's forbidden to upload files inside node_modules directory.

query Parameters
build
boolean

Do the build of applet version when file is uploaded. Accepted values '0', '1', 'true', 'false'.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Applet/Applet Tests

Test Applet By Version

Create new applet version test of applet by appletUid and appletVersion.

To create a new Applet version test suite you need just the binary (string with test source code).

Parameters

Field Type Required Description
appletUid string required Unique Applet identification
version string required Applet version

Body

Field Type Required Description
identifier string required Test suite identifier
binary string required Binary as string
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "identifier": "{{testIdentifier}}",
  • "binary": "console.log('OK');"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Test Applet By Version

Get all applet version tests of applet by appletUid & appletVersion.

Applet tests allow you to test the functionality and performance of your applets automatically.

Parameters

Field Type Required Description
appletUid string required Unique applet identification
appletVersion string (semver) required Version of your Applet, e.g. 1.0.12
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Test Applet By Version and Test Identifier

Get content from one applet version test of applet by appletUid , appletVersion and testIdentifier.

Applet tests allow you to test the functionality and performance of your applets automatically.

Parameters

Field Type Required Description
appletUid string required Unique applet identification
appletVersion string (semver) required Version of your Applet, e.g. 1.0.12
testIdentifier string required Name of the test suite
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

testIdentifier
required
string
Example: {{testIdentifier}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Responses

Response samples

Content type
application/json
{
  • "binary": "example-binary-content"
}

Test Applet By Version And Identifier

Update existing applet version test of applet by appletUid, appletVersion & testIdentifier

To update existing Applet version test suite you need just the binary (string with test source code).

Parameters

Field Type Required Description
appletUid string required Unique Applet identification
version string required Applet version
identifier string required Test suite identifier

Body

Field Type Required Description
binary string required Binary as string
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

testIdentifier
required
string
Example: {{testIdentifier}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "binary": "console.log('OK');"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Test Applet By Version And Identifier

Delete existing Applet version test by appletUid, appletVersion & testIdentifier.

Parameters

Field Type Required Description
appletUid string required Unique Applet identification
appletVersion string required Applet version
testIdentifier string required Test suite identifier
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

appletVersion
required
string
Example: {{appletVersion}}

Version of your Applet, e.g. 1.0.12

testIdentifier
required
string
Example: {{testIdentifier}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Alert

Get Alerts

Get all alerts for current Organization.

Parameters

Field Type Required Description
pagination number greater than 0
optional
 Start paginating result by a given number of items on the page. Next page link is available in the response header Link.

E.g.: <https://api.signageos/v1/alert?pagination=50&createdUntil=2020-10-22T16%3A10%3A00.000Z>; rel="next"
createdUntil string
optional
 Filter by alert createdAt lower than (exclusive) date time in ISO-8601 format. Internally used for pagination (see pagination parameter).
archived boolean
optional
 Filter archived/active alerts. Accepted values '0', '1', 'true', 'false'
query Parameters
pagination
integer
Example: pagination=50
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create Alert

Get all alerts for current Organization.

Parameters

Field Type Required Description
pagination number greater than 0 optional Start paginating result by a given number of items on the page. Next page link is available in the response header Link.

E.g.: ; rel="next"
createdUntil string optional Filter by alert createdAt lower than (exclusive) date time in ISO-8601 format. Internally used for pagination (see pagination parameter).
archived boolean optional Filter archived/active alerts. Accepted values '0', '1', 'true', 'false'

Body

Field Type Required Description
name string required Name of the new alert
organizationUid string required Uid of organization to which alert will be assigned
description string required Description of the alert
alertRuleUid string required Created alert rule that will be assigned to this new alert
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "New alert name",
  • "description": "new description",
  • "organizationUid": "{{organizationUid}}",
  • "alertRuleUid": "alert rule uid"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Alert

Get alert for current Organization by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "alertUid": "e8e6da9206f377289c2c5b8c0eb0155ee8f45c4f76b278085b",
  • "organizationUid": "43259e30b1423d4171e348d6a1a1222e3b0075c8d7ebac868a",
  • "description": "Alert for PB 5",
  • "alertRuleUid": "147c0d4a5846da4b4cfddf231744c4f4597eaf0b7c7610381f",
  • "createdAt": "2021-09-21T13:52:07.665Z",
  • "archivedAt": null,
  • "deviceUids": [ ],
  • "latelyChangedAt": "2021-09-21T13:52:07.665Z",
  • "snoozeRule": null
}

Update Alert Description

Update alert description by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification

Body

Field Type Required Description
description string required New description for updated alert
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "description": "new alert description"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Archive Alert

Archive one alert by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Unarchive Alert

Unarchive one alert by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
{
  "message\"": "OK"
}

Snooze Alert

Snooze one alert by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification

Body

Field Type Required Description
snoozeRule object required Properties for alert https://demo.signageos.io/dev/alerts/modules.html#snoozerule
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "snoozeRule": {
    }
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Snooze Device Alert

Snooze one alert on one device by alertUid and deviceUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
deviceUid string required Device unique identification

Body

Field Type Required Description
snoozeRule object required Properties for alert (only datetime is available) https://demo.signageos.io/dev/alerts/modules.html#snoozerule
path Parameters
alertUid
required
string
Example: {{alertUid}}
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "snoozeRule": {
    }
}

Response samples

Content type
text/plain
# Empty response

Unsnooze Device Alert

Unsnooze one alert on one device by alertUid and deviceUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
deviceUid string required Device unique identification

Body

Field Type Required Description
path Parameters
alertUid
required
string
Example: {{alertUid}}
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
# Empty response

Unsnooze Alert

Unsnooze one alert by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
{
  "message": "OK"
}

Assigne Devices to Alert

Assign device to alert by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification

Body

Field Type Required Description
alertUid string required Unique Alert Identification
deviceIdentityHashes array required Array of deviceUids that will be assigned to this alert.
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
"{\n \"alertUid\": {{alertUid}},\n \"deviceIdentityHashes\": [{{deviceUid}}]\n}"

Response samples

Content type
application/json
{
  • "message": "OK"
}

Unassigne Devices from Alert

Unassign alert from devices by alertUid.

Parameters

Field Type Required Description
alertUid string required Unique Alert Identification

Body

Field Type Required Description
alertUid string required Unique Alert Identification
deviceIdentityHashes array required Array of deviceUids that will be unassigned from this alert.
path Parameters
alertUid
required
string
Example: {{alertUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
"{\n \"alertUid\": {{alertUid}},\n \"deviceIdentityHashes\": [{{deviceUid}}]\n}"

Response samples

Content type
application/json
{
  • "message": "OK"
}

Alert/Rule

Get Alert Rules

Get list of all alert rules in your company.

Parameters

Field Type Required Description
pagination number optional Start paginating result by given number items on-page. Next page link is available on in response under header `Link`. E.g.: `; rel="next"`
archived boolean optional Filter archived alert rules. Accepted values '0', '1', 'true', 'false'
paused boolean optional Filter paused alert rules. Accepted values '0', '1', 'true', 'false'
name string optional Filter alert rules by name
alertType string optional Filter alert rules corresponding with type. Accepted values 'DEVICE', 'POLICY', 'APPLET'
query Parameters
alertType
string
Example: alertType=DEVICE
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create Alert Rule

Create a new alert rule within your company by companyUid.

Parameters

Field Type Required Description
No parameters

Body

FIeld Type Required Description
name string required Name of the new alert rule
companyUid string required Unique Company Identification
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "alert rule name",
  • "companyUid": "{{companyUid}}"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Alert Rule

Get one specific alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "alertRuleUid": "9af876c55c17cf13c123261eaac78e59e9d2b5d913a79bf96c",
  • "name": "Test Fry",
  • "companyUid": "7fc1f0cd1b0ae527468fbe6b7a5a98b4cd93872235e11c6aaf",
  • "createdAt": "2021-05-25T18:45:54.983Z"
}

Update Alert Rule

Update one existing alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification

Body

Field Type Required Description
name string optional New name of the updated alert rule
description string optional New description
alertType string optional Accepted values 'DEVICE', 'POLICY', 'APPLET'
organizationUids array optional Organizations which is checked against the rule
filter object optional Pre-filter of devices which the alert will be checked against. It's used for percentage threshold of alert creation as base. The mandatory filter is organization set above. This is extended filter for example device applicationType (tizen, webos, etc.).
conditions object optional Specify all conditions which devices has to match to state alert as applicable.
threshold object optional Specify threshold of rule. It is comparing number of devices matched the conditions above relatively against the total number devices filtered by filter above
periodicity object optional Specify how often the rule will be checked against the current state of devices.
action object optional Optionally specify the action of alert rule. This action will happen when alert rule is creating an alert.

Filter

Field Type Required Description
applicationType string optional Type of application one of ('sssp', 'tizen', 'webos', 'android', 'chrome', 'brightsign', 'linux', 'windows', 'default' )
applicationVersion array optional Semver comparison of core app version [SemverOperator, string] - ([">", "3.12.0"])
frontDisplayVersion array optional Semver comparison of internal front-display library version[SemverOperator, string] - ([">", "9.15.0"])
firmwareType string optional Partial matching of string
firmwareVersion string optional Partial matching of string
managementPackageVersion array optional Semver comparison of core management package version ([">", "3.12.0"])
frontPackageVersion array optional Semver comparison of core front package version ([">", "3.12.0"])
tagUids string optional List of tags. Device has match all tags in list
model string optional Partial matching of string
name string optional Partial matching of string
extendedManagement boolean optional Filter device with or without extended management
extendedManagement Date optional Filter only devices provisioned since the date
supportedResolutions ResolutionItem optional Filter only devices supporting specified resolution
locationUids array optional Filter only devices in specified locations
locationTagsUids array optional Filter only devices in specified location tags

Conditions

NumericOperator

Operators
>
<
<=
>=
=
!=

TimeRangeOperator

Operators
>
<

Conditions values types

Condition type Type Example
OCCURRENCES_IN_TIME_RANGE_TO_PAST array [operator: NumericOperator, occurrences: number, rangeInPastMs: number] -([">", 12, 36000])
NUMERIC_RANGE array [operator: NumericOperator, nmbr: number] - (">", 12)
STRING_OCCURRENCES_IN_TIME_RANGE_TO_PAST array [str: string, operator: NumericOperator, occurrences: number, rangeInPastMs: number] - ("action", ">" 12, 36000)
TIME_RANGE_TO_PAST array [operator: TimeRangeOperator, rangeInPastMs: number] - ("<", 36000)
PERCENTAGE_RANGE array [operator: NumericOperator, percentage: number] - ("<", 50)
NUMERIC_RANGE array [operator: NumericOperator, nmbr: number] - ("<", 50)
NUMERIC_RANGE string 'DEVICE'
MATCH_SEMVER array [operator: SemverOperator, version: string] - (">", "3.12.0")
STRING_LIST array ["string1", "string2"]
POLICY_LIST string One of ('VOLUME', 'BRIGHTNESS', 'TIMERS', 'PROPRIETARY_TIMERS', 'RESOLUTION', 'ORIENTATION', 'REMOTE_CONTROL', 'APPLICATION_VERSION', 'FIRMWARE_VERSION', 'DEBUG', 'DATETIME', 'POWER_ACTIONS_SCHEDULE', 'TEMPERATURE', 'BUNDLED_APPLET')
WIFI_OR_ETHERNET string One of ('wifi', 'ethernet')
INPUT_SOURCE string One of ('urlLauncher', 'hdmi1', 'hdmi2', 'hdmi3', 'hdmi4')
TIMERS array TimerSettings[]
RESOLUTION object ResolutionItem
ORIENTATION object OrientationSettings

Device condition

Condition Condition values Description
INCORRECT_TIME BOOLEAN Is used when device has incorrect time based on current time & timezone of device
INVALID_SSL_CERTIFICATE BOOLEAN Is used when device is detected having some problems with SSL certificates (it can be even time related)
FAILED_ACTIONS BOOLEAN Is used when device performing/executing action has failed for amount of time in past
CONNECTIONS BOOLEAN Is used when device performing/executing action has failed for amount of time in past
MODEL array BOOLEAN if device has model or not
SERIAL_NUMBER BOOLEAN Check if device has serial number or not
NAME string Check if device partially match some string
PIN_CODE boolean Check if device has PIN code reported
MANAGEMENT_PACKAGE_VERSION MATCH_SEMVER Check if device match semver version
FRONT_PACKAGE_VERSION MATCH_SEMVER Check if device match semver version
FRONT_DISPLAY_VERSION MATCH_SEMVER Check if device match semver version
FIRMWARE_TYPE string Check if device match semver version
TAG_UIDS STRING_LIST Check if device has selected tags
POLICIES POLICY_LIST Check if device has selected policy settings
LAST_PROVISION_AT TIME_RANGE_TO_PAST Check if device was provisioned in specified time range in past. Useful to detect new devices are provisioned
LAST_DEPROVISION_AT TIME_RANGE_TO_PAST Check if device was deprovisioned in specified time range in past. Useful to detect devices are re-provisioned
EXTENDED_MANAGEMENT BOOLEAN Check if device has access to extended management
ALIVE_AT TIME_RANGE_TO_PAST Check if device last ping in specified time range in past
NETWORK_INTERFACES WIFI_OR_ETHERNET Check if device is connected using WiFi or Ethernet
BATTERY_STATUS PERCENTAGE_RANGE Check if device has enough or not enough battery
STORAGE_STATUS PERCENTAGE_RANGE Check if device has or has not enough free storage
CURRENT_TIMEZONE MATCH_STRING Check if timezone match the string
DISPLAY_SETTING_BACKLIGHT PERCENTAGE_RANGE Check if match expected value of display settings
DISPLAY_SETTING_CONTRAST PERCENTAGE_RANGE Check if match expected value of display settings
DISPLAY_SETTING_SHARPNESS PERCENTAGE_RANGE Check if match expected value of display settings
DISPLAY_SETTING_MAX_TEMPERATURE NUMERIC_RANGE Max temperature in celsius
INPUT_SOURCE INPUT_SOURCE Check if current input source is set to specified source
VOLUME PERCENTAGE_RANGE Check if current volume is expected
BRIGHTNESS PERCENTAGE_RANGE Check if current brightness is expected
TIMERS TIMERS Check if current native timers are set as expected
PROPRIETARY_TIMERS TIMERS Check if current proprietary timers are set as expected
RESOLUTION RESOLUTION Check if current resolution is set as expected
ORIENTATION ORIENTATION Check if current orientation is set as expected
REMOTE_CONTROL BOOLEAN Check if current RC is locked or not
APPLICATION_VERSION MATCH_SEMVER Check if current core app version is correct
FIRMWARE_VERSION MATCH_STRING Check if current FW version match some string
DEBUG BOOLEAN Check if debug is enabled or not
POWER_ACTIONS_SCHEDULE SCHEDULED_POWER_ACTIONS Check if current scheduled power actions are correctly set
TEMPERATURE NUMERIC_RANGE Check if current scheduled power actions are correctly set
INSTALLED_PACKAGE MATCH_STRING Check if specified package is installed
SCREENSHOT OCCURRENCES_IN_TIME_RANGE_TO_PAST Check if number of screenshots was received in time
FEATURE_TESTS BOOLEAN Check if feature tests has passed

Policy condition

Condition Condition values Description
POLICY_VIOLATION_VOLUME BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_BRIGHTNESS BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_TIMERS BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_PROPRIETARY_TIMERS BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_RESOLUTION BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_ORIENTATION BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_REMOTE_CONTROL BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_APPLICATION_VERSION BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_FIRMWARE_VERSION BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_DEBUG BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_DATETIME BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_POWER_ACTIONS_SCHEDULE BOOLEAN Check violation of any of existing policy device settings type
POLICY_VIOLATION_TEMPERATURE BOOLEAN Check violation of any of existing policy device settings type

Applet condition

Condition Condition values Description
APPLET_COMMAND STRING_OCCURRENCES_IN_TIME_RANGE_TO_PAST Is used when to check custom user defined commands occurrences in time

Threshold

Field Type Required Description
type string required Currently only percentage implemented - percentage'
percentage number required The number of percent from 0 to 99 (100 is never matched)

Periodicity

Field Type Required Description
interval string required How often alert will be checked against current state in SECONDS'
activeTimeWindows array required Alert rule won't be checked against current state out of specified active time windows when at least one specified. If no active time window specified, alert rule will be checked anytime.

Action

Account alert actions

Action type Type Required Description
type string required All specified accounts are notified using account notification settings' - (type: 'accounts')
accountIds array of accountIds required AccountIds in array, which will be notified about alert

Organization accounts alert actions

Action type Type Required Description
type string required All accounts assigned to organization of creating rule are notified using account notification settings' (type: 'organization_accounts')

Email alert actions

Action type Type Required Description
type string required All accounts assigned to organization of creating rule are notified using account notification settings' (type: 'emailAddresses')
emailAddresses array of emails required Array of email addresses, which will be notified about alert
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "My updated Alert rule name",
  • "description": "Some sort of updated",
  • "alertType": "DEVICE",
  • "organizationUids": [
    ],
  • "conditions": {
    },
  • "filter": {
    },
  • "threshold": {
    },
  • "periodicity": 30,
  • "action": {
    }
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Archive Alert Rule

Archive one alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
# Empty response

Unarchive Alert Rule

Unarchive one alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Pause Alert Rule

Pause one alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
# Empty response

Unpause Alert Rule

Unpause one alert rule by alertRuleUid.

Parameters

Field Type Required Description
alertRuleUid string required Unique Alert Rule Identification
path Parameters
alertRuleUid
required
string
Example: {{alertRuleUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
text/plain
# Empty response

BulkProvisioning/Recipe

Create Provision recipe

Creates a new Provision recipe for current Organization

Body

Field Type Required Description
brand string required
seriaNumber string optional
model string optional
macAddress string optional
tagUids string optional List of tags.
deviceName string optional
policyUid string optional Unique policy identification.
locationUid string optional
header Parameters
x-auth
string
Example: {{x-auth-account}}

Account authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "deviceName": "Nice device name",
  • "serialNumber": "1",
  • "macAddress": "12:34:56:78:90:ab",
  • "model": "Good Display LCD",
  • "brand": "Good Display",
  • "tagUids": [
    ],
  • "policyUid": "1234567890c641df0b1a1701a1c6efb93fe053a8faeba5bce2",
  • "locationUid": "123456789071821f914dcfbca02e6a27dd0eaf74b853f108cc"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Provision recipes

Get all provision recipes for current Organization.

query Parameters
limit
number
Example: limit=50

Start paginating result by given number items on page. Next page link is available in response under header Link. E.g.: <https://api.signageos/v1/example?limit=50&until=2020-10-22T16%3A10%3A00.000Z>; rel="next"

descending
boolean
Default: true
Example: descending=true

Default true. Order resource in descending or ascending order by createdAt.

search
string
Example: search=TV

search by string contained in model, brand, serialNumber or macAddress

status
string
Enum: "Pending" "Applied"
Example: status=Pending

filter by device status

brand
string
Example: brand=Sony

filter by device brand

tagUids
Array of strings
Example: tagUids={{tagUid}}

filter by list of tags

policyUids
Array of strings
Example: policyUids={{policyUid}}

filter by list of policies

locationUid
string
Example: locationUid={{locationUid}}

filter by location

model
string
Example: model=LGE-55SM5C-BF-1

filter by device model matching

macAddress
string
Example: macAddress=12:34:56:78:90:ab

filter by device mac address

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Provision recipe

Get Provision recipe for current Organization by recipeUid.

Parameters

Field Type Required Description
recipeUid string required
path Parameters
recipeUid
required
string
Example: {{recipeUid}}
header Parameters
x-auth
string
Example: {{x-auth-account}}

Account authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "status": "Pending",
  • "uid": "1234567890c7dbe8ccd61e80e30d46b12902",
  • "organizationUid": "1234567890423d4171e348d6a1a1222e3b0075c8d7ebac868a",
  • "model": "Good Display LCD",
  • "brand": "Good Display",
  • "macAddress": "12:34:56:78:90:ab",
  • "serialNumber": "1"
}

Update Provision recipe

Update existing Provision recipe for current Organization

Parameters

Field Type Required Description
recipeUid string required

Body

Field Type Required Description
brand string optional
seriaNumber string optional
model string optional
macAddress string optional
tagUids string optional List of tags.
deviceName string optional
policyUid string optional Unique policy identification.
locationUid string optional
path Parameters
recipeUid
required
string
Example: {{recipeUid}}
header Parameters
x-auth
string
Example: {{x-auth-account}}

Account authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "deviceName": "Different name",
  • "model": "Bad Display LCD"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Delete Provision recipe

Delete Provision recipe for current Organization by recipeUid.

Parameters

Field Type Required Description
recipeUid string required
path Parameters
recipeUid
required
string
Example: {{recipeUid}}
header Parameters
x-auth
string
Example: {{x-auth-account}}

Account authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Upload provisioning recipes via CSV file

Creates a new Provision recipes for current Organization by uploading CSV file

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Request Body schema: text/csv
string <binary>

Responses

Response samples

Content type
application/json
{
  • "message": "OK",
  • "linesProcessed": 2
}

Device

Device is any digital signage display, player, Windows machine, Raspberry Pi 3, and Raspberry Pi 4. You can see all supported devices here

No matter what device you are using, the APIs are standardized across all of them.

Get Devices v1 Deprecated

This endoint is deprecated and will be removed in the future. Use Get Devices v2 instead.

Get all devices for current Organization.

Parameters

Field Type Required Description
applicationType string - ‘sssp’ , ‘tizen’ , ‘webos’ , ‘android’ , ‘linux’ , ‘default’
optional
 one of supported applicationTypes
search string
optional
 search by string contained in uid, duid, name of device, serial number, MAC address or verification hash
model string
optional
 filter by device model matching
minStorageStatusPercentage number 0 – 100
optional
 filter by storage usage minimal value in percentage
maxStorageStatusPercentage number 0 – 100
optional
 filter by storage usage maximal value in percentage
pagination number greater than 0
optional
 Start paginating result by a given number of items on the page. Next page link is available in the response header Link.

E.g.: <https://api.signageos/v1/device?pagination=50&createdUntil=2020-10-22T16%3A10%3A00.000Z>; rel="next"
createdSince string
optional
 filter by device createdAt greater than or equal (inclusive) date time in ISO-8601 format.
createdUntil string
optional
 filter by device createdAt lower than (exclusive) date time in ISO-8601 format. Internally used for pagination (see pagination parameter).

Important note

For Organizations with more than 500 devices, we strongly recommend using pagination.

query Parameters
pagination
integer
Example: pagination=50

Start paginating result by given number items on page. Next page link is available on in response under header Link. E.g.: <https://api.signageos/v1/device?pagination=50&createdUntil=2020-10-22T16%3A10%3A00.000Z>; rel="next"

applicationType
string
Enum: "sssp" "tizen" "webos" "android" "brightsign" "linux" "windows" "default" "chromeos"
Example: applicationType=webos

filter by application type

search
string
Example: search=Marge

search by string contained in uid, duid or name of device

model
string
Example: model=LGE-55SM5C-BF-1

filter by device model matching

maxStorageStatusPercentage
integer
Example: maxStorageStatusPercentage=20

filter by storage usage maximal value in percentage

minStorageStatusPercentage
integer

filter by storage usage minimal value in percentage

createdSince
string
Example: createdSince=2017-08-02T13:45:39.000Z

filter by device createdAt greater than or equal (inclusive) date time in ISO-8601 format.

createdUntil
string
Example: createdUntil=2017-08-02T13:45:40.000Z

filter by device createdAt lower than (exclusive) date time in ISO-8601 format. Internally used for pagination (see pagination parameter).

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Devices v2

Get all devices for current Organization.

This endpoint uses pagination. For more information view Pagination section. Max allowed page size is 1000.

query Parameters
applicationType
string
Enum: "sssp" "tizen" "webos" "android" "brightsign" "linux" "windows" "default" "chromeos"
Example: applicationType=tizen

filter by application type

search
string
Example: search=Marge

search by string contained in uid, duid or name of device

model
string
Example: model=LGE-55SM5C-BF-1

filter by device model matching

brand
string
Example: brand=Sony

filter by device brand

osVersion
string
Example: osVersion=6.5

filter by device OS version

serialNumber
string
Example: serialNumber=EQK70AAY72Y8

filter by serial number

firmwareVersion
string
Example: firmwareVersion=4.3.0

filter by firmware version

locationUid
string
Example: locationUid={{locationUid}}

filter by location

appletUids
Array of strings
Example: appletUids={{appletUid}}

filter by list of applets

policyUids
Array of strings
Example: policyUids={{policyUid}}

filter by list of policies

tagUids
Array of strings
Example: tagUids={{tagUid}}

filter by list of tags

alertUid
string
Example: alertUid={{alertUid}}

filter by alert

hasPolicy
boolean
Example: hasPolicy={{hasPolicy}}

filter if device is assigned to any policy or not

limit
integer
Example: limit={{limit}}

Page size. For more information, view Pagination section.

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Device v1 Deprecated

This endoint is deprecated and will be removed in the future. Use Get Device v2 instead.

Get one device detail by deviceUid.

Parameters

Field Type Required Description
deviceUid string required Unique Device Identification
applicationType string/Enum optional One of supported applicationTypes

tizen, webos, android, linux, brightsign, windows
search string optional Search by string contained in uid, duid, name of device, serial number, MAC address or verification hash
model string optional Filter by device model matching
minStorageStatusPercentage number 0 – 100 optional Filter by storage usage minimal value in percentage
maxStorageStatusPercentage number 0 – 100 optional Filter by storage usage maximal value in percentage
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "uid": "750dbe59c81b60170b3c2b10650fb200cc82d34e6b0120fc344322",
  • "duid": "a69a6f99f89fa3c9df73759c2fca2164f2e695260fef5d234232e",
  • "name": "Test Emulator",
  • "createdAt": "2021-04-07T16:11:13.485Z",
  • "aliveAt": "2021-04-10T13:54:38.226Z",
  • "pinCode": "0000",
  • "applicationType": "default",
  • "applicationVersion": "8.7.0",
  • "frontDisplayVersion": "8.7.0",
  • "firmwareVersion": "Chrome-89.0.4389.114",
  • "model": "Win32",
  • "serialNumber": "5A1FC776B031",
  • "brand": "signageOS",
  • "osVersion": "1.0.0",
  • "organizationUid": "f4dc889c5bfae798bd652e5d0989e6805d45131b75305fba4c",
  • "networkInterfaces": {
    },
  • "storageStatus": {
    },
  • "connections": [ ],
  • "batteryStatus": null,
  • "currentTime": {
    }
}

Update Device Name Deprecated

This endpoint is deprecated and will be removed in the future. Use v2 PUT Configure Device instead. Update one device by deviceUid - Set device name.

Parameters

Field Type Required Description
deviceUid string
required
 unique device identification

Body

Field Type Description
name string device name, eg. Reception Display
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/x-www-form-urlencoded
name
string

device name, eg. Reception Display

Responses

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Device v2

Get one device detail by deviceUid.

path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "uid": "c0752280cc7d009c57422be6927b660d7d71456d76b5e2dgdfgdfgd",
  • "duid": "2221b195b6350a6c71318e56e4d493a585f42b6d9c387wqqww334",
  • "name": "Test Emulator",
  • "createdAt": "2021-04-18T22:26:39.405Z",
  • "applicationType": "default",
  • "firmwareVersion": "Chrome-89.0.4389.114",
  • "model": "Linux x86_64",
  • "serialNumber": "EQK70AAY72Y8",
  • "organizationUid": "f4dc889c5bfae798bd652e5d0989e6805d45131b753dwwfgrte",
  • "locationUid": "qn7tks6io6vckl59hxpnmgbzdzxwob3xsh0ezowsqi8cox08o3",
  • "connectionMethod": "websocket"
}

Configure Device

Configure Device by deviceUid.

path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
name
string
connectionMethod
string
Enum: "websocket" "http"
platformUri
string
staticBaseUrl
string
uploadBaseUrl
string
weinreUri
string
extendedManagementUrl
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connectionMethod": "websocket",
  • "platformUri": "string",
  • "staticBaseUrl": "string",
  • "uploadBaseUrl": "string",
  • "weinreUri": "string",
  • "extendedManagementUrl": "string"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Device Authentication Hash

Get authentication contains the authHash for device by deviceUid.

Get device Authentication Hash which is used for device-CMS authentication.

Parameters

Field Type Required Description
deviceUid string required device application id
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "deviceUid": "9c83b5e07ee0991dce1216e2ba0338d454f1da7d4f8440676dwdaww",
  • "authHash": "auth-hash-key",
  • "createdAt": "2021-04-25T19:28:05.835Z"
}

Get Device by Authentication Hash

Get device by Authentication Hash which is used for device-CMS authentication by authHash. JS api sos.authHash JS API Basics.

Parameters

Field Type Required Description
authHash string
required
 device autHash from applet (can be used only 6 or more first characters of authHash)
path Parameters
deviceAuthHash
required
string
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "deviceUid": "9c83b5e07ee0991dce1216e2ba0338d454f1da7d4f84406dwewwq",
  • "authHash": "device-auth-hash",
  • "createdAt": "2021-04-25T19:28:05.835Z"
}

Device/ActionLog (Device History)

Get device history

Action log includes complete history of actions performed with the device as well as the action originator (user/api) and the result. You can see the Action log in a History tab on device detail page in Box.

Parameters

Field Type Required Description
deviceUid string
required
 unique device identification
descending boolean
optional
 true or false
limit number
optional
 limit the number of returned results
since timestamp
optional
 limit result by date and time
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Device/Application Version and update

To use any of the supported devices, you need the signageOS Core App. signageOS Core Apps are a natively-built application for various platforms allowing you to run your HTML5/JS application (aka Applet).

Update Core App Version

Request upgrade of the signageOS Core App version by deviceUid.

Parameters

Field Type Required Description
deviceUid string required Device application id
applicationType string - ‘sssp’ ‘tizen’ ‘webos’ ‘android’ ‘chrome’ ‘default’ required One of supported applicationTypes

Body

content-type: application/json or application/x-www-form-urlencoded

Field Type Description
version string sOS Core App version you want to set to device
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
applicationType
required
string
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "version": "{{applicationVersion}}"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Current Core App Version

Get version of sOS Core App on device.

Parameters

Field Type Required Description
deviceUid string
required
 device application id
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Device/Applet Command

Create Applet Command

Create device applet command by deviceUid & appletUid which will be delivered to device current active applet.

Command may contain any number of custom properties. The only required one is type which is used to identify the command.

Originally the command was sent using the commandPayload field, which is now deprecated. The command field should be used instead.

Once the command is sent, it can be received inside the applet using the following customField:

sos.command.onCommand((commandEvent) => {
  if (commandEvent.command.type === 'TestCommand') {
    console.log(commandEvent.command.customField)
  }
});

For more information, refer to the JS API documentation.

Parameters

Field Type Required Description
deviceUid string required Device unique identification
appletUid string required Applet unique identification
path Parameters
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
required
object

Command object. Must contain at least type. May contain any number of custom properties.

type
required
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "command": {
    }
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Applet Commands

Get all device applet commands by deviceUid.

Max allowed page size is 200

Device applet commands are available for the previous 3 days. Historical data of all commands is available as ZIP dump at Get Device Reports (Uptime, Applet Commands) endpoint: https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/~1v1~1device~1%7BdeviceUid%7D~1report/get .

Parameters

Field Type Required Description
deviceUid string <div class="red">required
device unique identification appletUid string <div class="yellow">optional
applet unique identification type string <div class="yellow">optional
your log type - e.g.: MyCms.Content.PlayVideo receivedSince Date <div class="yellow">optional
get all commands since exact date (included) receivedUntil Date <div class="yellow">optional
get all commands till exact date (excluded)

Sample response

Server never returns all data matching the parameters. Instead, it divides them into pages. First request returns data up to max. size of a page - 200 records. If more data is available, it returns a header Link with a link to the next page.

path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Applet Command By Command UID

Get one device applet command by deviceUid, appletUid & timingCommandUid.

Get commands – information on how the device operates or was set – for the specific device. You can access all device logs, including your custom logs, within this API call.

Device applet commands are available for the previous 3 days. Historical data of all commands is available at Data report CSV dump.

Parameters

Field Type Required Description
deviceUid string required Device unique identification
appletUid string required applet unique identification
commandUid string required Command unique identification

Sample response

Server never returns all data matching the parameters. Instead, it divides them into pages. First request returns data up to max. size of a page. If more data is available, it returns a header Link with a link to the next page.

path Parameters
deviceUid
required
string
Example: {{deviceUid}}
appletUid
required
string
Example: {{appletUid}}

Unique Applet Identifier

commandUid
required
string
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Device/Brightness

Update Device Brightness

Request change device brightness by deviceUid.

Parameters

Field Type Required Description
deviceUid string <div class="red">required
device application id

Body

Field Type Description
brightness1 number device brightness in percent 0-100
timeFrom1 HH:MM:SS starting time for brightness 1
brightness2 number device brightness in percent 0-100
timeFrom2 HH:MM:SS starting time for brightness 2
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "brightness1": 90,
  • "timeFrom1": "09:00:00",
  • "brightness2": 40,
  • "timeFrom2": "20:00:00"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Device Brightness

Get requested device brightness changes by deviceUid.

Parameters

Field Type Required Description
deviceUid string required device application id
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Device/Debug

Set Device Debug

Request begin device debug mode by deviceUid. Set debug flag for device to enable remote debugging.

Parameters

Field Type Required Description
deviceUid string required Device application id

Body

content-type: application/json or application/x-www-form-urlencoded

Field Type Description
appletEnabled boolean Enable weinre for device inside Applet
nativeEnabled boolean Enable native debug

Note 1

Applet debug settings is only on-demand. So when you set it, the inspection tool is started. Once you do the REBOOT, RESTART, RELOAD or REFRESH power action, the tool is stopped & you must set debug again (turn it off then on again in BOX).

Note 2

Native debug settings behavior differs in every device OS brand (SSSP, Tizen, WebOS1,2+, Android etc.). Here are mentioned a little differences however for more info you can look at official documentation of display manufacturer.

path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "appletEnabled": true,
  • "nativeEnabled": false
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Device Debug

Get begin device debug mode requests by deviceUid

Parameters

Field Type Required Description
deviceUid string <div class="red">required
device application id
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Device/Firmware

Update Device Firmware

Request change device firmware version by deviceUid.

Set/upgrade Firmware version of a device.

Parameters

Field Type Required Description
deviceUid string required Device uid

Body

content-type: application/json or application/x-www-form-urlencoded

Field Type Description
version string ex.: T-HKMLAKUC-2020.5 Version of FW you want to upgrade to. Versions layout differs vendor to vendor.
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "version": "x86_64"
}

Response samples

Content type
application/json
{
  • "message": "OK"
}

Get Device Firmware

Get last changed device firmware version requested to deviceUid. Get Firmware version last successfully sent to the device.

Parameters

Field Type Required Description
deviceUid string required device application id
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "uid": "DEVICE_CREATE_UID:d342377e18f83bc08d76c44e8b35c05c4e786f2bd3f7aeb42d",
  • "deviceUid": "c0752280cc7d009c57422be6927b660d7d71456d76b5e2c9613bc",
  • "createdAt": "2021-04-18T22:26:39.405Z",
  • "succeededAt": null,
  • "failedAt": null
}

Device/Monitoring

Get Device Hourly Connected Status

DEPRECATED in favor of:

https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/1v11device1%7BdeviceUid%7D1report/get

and

https://developers.signageos.io/api/#tag/DeviceApplet-Command

Get all device connected status grouped hourly by deviceUid.

Parameters

Field Type Required Description
deviceUid string required Device unique identification
from Date optional Get all statistics from exact date (included)
to Date optional Get all statistics to exact date (included)
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Device Reports (Uptime, Applet Commands)

Get all device report files by deviceUid.

Get Report files – historical data containing Device Applet commands, Applet Ready events, Connected/Disconnected actions.

Parameters

Field Type Required Description
deviceUid string required device unique identification
createdSince Date optional get all reports since exact date (included)
createdUntil Date optional get all reports till exact date (excluded)
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
query Parameters
createdSince
string
Example: createdSince=2016-08-02T13:45:39.000Z

get all reports since exact date (included)

createdUntil
string
Example: createdUntil=2017-08-02T13:45:39.000Z

get all reports till exact date (excluded)

header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[]

Get Device Temperature

Get all device temperature logs by deviceUid.

Get logs of device temperature in time.

Parameters

Field Type Required Description
deviceUid string required Device unique identification
createdSince Date optional Get all temperature logs since exact date (included) - Example: 2018-09-09T10:49:33.352Z
createdUntil Date optional Get all temperature logs until exact date (excluded) - Example: 2018-09-10T10:49:33.352Z
path Parameters
deviceUid
required
string
Example: {{deviceUid}}
header Parameters
x-auth
string
Example: {{x-auth}}

Authorization key and token

Content-Type
string
Example: application/json

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {