Deprecated - Do Not Use

The details below only apply to our legacy product, Signage. New users can no longer create accounts on Signage, and at a future date it will be retired entirely.

Studio, the new version of ScreenCloud, offers infintitely more flexibility and a huge range of extra content features.

If you're still on Signage and would like to build something using an API, please reach out to our team for a free migration to Studio. All of the Studio API docs can be found here.

Authentication

Access to the API requires your organisation ID - which will be a UUID - and an API key. Both of these can be found and created within the API keys section of your account settings. You must be an admin to create API keys.

Each API key will have permissions that depend upon both the team that it's attached to, and the role that it has. An API key can have two different roles; that of 'user', and 'admin'. A 'user'-level key can only access resources within the team that it's attached to, whereas an 'admin'-level key can access all resources from all teams.

Your http requests are then authenticated via basic auth, with username given by your organisation ID, and password given by an API key.

Pagination

Pagination for endpoints that return multiple resources is handled via url query parameters. These are 'offset' (defaults to 0) and 'limit' (defaults to 100; max is 200), which can be used to control the starting point of the returned list, and the number of returned resources, respectively.

Error responses

Any responses that produce a non-2xx status code will return a body of the form:

{
  errCode: <string>,
  errMsg: <string>
}

Where errCode will be a string aimed at being easily machine readable (e.g. 'NOT_FOUND'); whereas errMsg will be a human readable message.

Resources

The API can be used to view and control five different types of resources: teams, screens, content, playlists, and schedules. Their schemas are as follows:

Teams

{
  id: <string - UUID>,
  created_at: <string - ISO 8601 date>,
  name: <string>
}

Screens

{
  id: <string>,
  created_at: <string - ISO 8601 date>,
  name: <string>,
  device_platform: <string>,
  device_model: <string>,
  sections: <array - see below>,
  status: <string - one of 'live', 'previewing', 'paused', 'suspended'>
}

Where sections is an array of objects, with each object describing a section within the layout of the screen. These objects will have the form:

{
  playable: <string - see below>,
  positioning: {
     top: <string - percentage>,
     bottom: <string - percentage>,
     left: <string - percentage>,
     right: <string - percentage>
 }
}

Where playable is a string of the form <resource type>/<resource id>. e.g. if that section is showing a playlist with id -KDhqZ2A04jM_oHMWJED then playable will be playlist/-KDhqZ2A04jM_oHMWJED and if it's just playing a video (i.e. single piece of content on loop) with id -KxJTmbXnEK0WkJ8wN6a then playable will be content/-KxJTmbXnEK0WkJ8wN6a. playable can also be the empty string to indicate that nothing is playing in that section.

The positioning property is an object indicating how the section should be positioned on-screen. Each of it's properties indicate how far the section is from the corresponding edge, much like the CSS rules for top, bottom, etc. The difference with CSS rules is that, here, only percentages are used/accepted. These percentages must be between 0 and 100, and can have a maximum of two decimal places. e.g. '0%', '33.33%', '73.8%', '100%'. All of the properties are optional, and will default to '0%' if missing.

Content

{
  id: <string>,
  app_id: <string>,
  created_at: <string - ISO 8601 date>,
  name: <string>,
  mime_type: <string - MIME type>,
  optimising_status: <string - one of 'pending', 'success', 'failed'>,
  thumbnail: <string - protocol-relative url>
}

Where mime_type is the mime type of the optimised content; and optimising_status indicates the state of the content's optimising process.

{
  id: <string>,
  created_at: <string - ISO 8601 date>,
  name: <string>
}

Schedules

{
  id: <string>,
  created_at: <string - ISO 8601 date>,
  name: <string>
}

Endpoints

All endpoints have a base of https://signage-api.screen.cloud/api/v1/

GET /me

This simply returns the organisation id, team id, and role of the API key used to authenticate the request.

GET /teams

Returns an array of the teams attached to the account.

GET /teams/<team_id>/screens/<screen_id>

GET /teams/<team_id>/content/<content_id>

GET /teams/<team_id>/playlists/<playlist_id>

GET /teams/<team_id>/schedules/<schedule_id>

Returns the resource as described above in the resources section.

GET /teams/<team_id>/screens

GET /teams/<team_id>/content

GET /teams/<team_id>/playlists

GET /teams/<team_id>/schedules

Returns an array of the resources attached to the team identified by team_id. Results are paginated.

PUT /teams/<team_id>/screens/<screen_id>/sections

Used to set the playing content on a screen. The request body should be an array of objects - one for each section in the layout - of the form:

{
  playable: <string> (required),
  positioning: <object> (optional)
}

Where positioning and playable are as described above in the resources section. Setting playable to the empty string will stop content from playing within that section.

PUT /teams/<team_id>/screens/<screen_id>/takeover

Used to takeover a screen with a type of playable, interrupting the screen. The request body should be an object of the following form:

{
  url: <string - protocol-relative url> (*optional),
  content_id: <string> (*optional),
  mime_type: <string - MIME type> (required),
  duration: <integer> (optional),
  num_loops: <integer> (optional)
}

Where url is the location of the content for screen takeover; content_id is the id of the screencloud-content for takeover; mime_type is the MIME type of the content found at the given location; duration is an optional length of time in milliseconds, which when not specified results in a continuous takeover; num_loops is the number of times for the content to sequentially takeover.

* Only one of url and content_id are required, but both are allowed. If both are present, url will take precedence.

DELETE /teams/<team_id>/screens/<screen_id>/takeover

Removes the current takeover on a screen.