API reference

Note

This page is generated from the API contract (OpenAPI document). Import it into Postman, Insomnia or code generators.

Account

GET /api/ext/v1/me

The key’s customer, name and permissions

Permission: none (any key)

Responses: 200 ExtMe

Locations

GET /api/ext/v1/locations

Locations

Permission: screens:read

Parameters

Name	In	Type	Required
page	query	integer	—
pageSize	query	integer	—

Responses: 200 ExtPageOfExtLocation

Screens

GET /api/ext/v1/screens

Screens with their devices and live status; filter by location, tag and online state

Permission: screens:read

Parameters

Name	In	Type	Required
locationId	query	uuid	—
tag	query	string	—
online	query	boolean	—
page	query	integer	—
pageSize	query	integer	—

Responses: 200 ExtPageOfExtScreen

GET /api/ext/v1/screens/{id}

A screen with its device and live status

Permission: screens:read

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 ExtScreen

PUT /api/ext/v1/screens/{id}

Writes all screen settings (name, location, default playlist, orientation, tags, opening hours)

Permission: screens:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: ExtScreenSettings

Responses: 200 ExtScreen · 400 Bad Request

POST /api/ext/v1/screens/{id}/commands

Remote command; read the result from the command record

Permission: screens:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: ExtCommandRequest

Responses: 202 ExtCommand · 400 Bad Request

GET /api/ext/v1/screens/{id}/commands/{commandId}

Command status

Permission: screens:read

Parameters

Name	In	Type	Required
id	path	uuid	yes
commandId	path	uuid	yes

Responses: 200 ExtCommand

GET /api/ext/v1/screens/{id}/screenshot

Latest app screenshot (send a screenshot command first)

Permission: screens:read

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 ExtScreenshot

Media and folders

GET /api/ext/v1/media

Media library (newest first); filter by folder, type and status

Permission: content:read

Parameters

Name	In	Type	Required
folderId	query	uuid	—
type	query	string	—
status	query	string	—
page	query	integer	—
pageSize	query	integer	—

Responses: 200 ExtPageOfExtMedia

GET /api/ext/v1/media/{id}

A media item

Permission: content:read

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 ExtMedia

PUT /api/ext/v1/media/{id}

Name and folder

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: ExtMediaUpdate

Responses: 200 ExtMedia · 400 Bad Request

DELETE /api/ext/v1/media/{id}

Moves to the trash (30 days); media used in a playlist is not deleted

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 204 No Content

POST /api/ext/v1/media/uploads

Upload address (30 min); PUT the file to it, then call complete

Permission: content:write

Body: ExtUploadRequest

Responses: 201 ExtUpload · 400 Bad Request

POST /api/ext/v1/media/{id}/complete

Upload finished: the file is checked on the server and queued for processing; use it once ready

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 202 ExtMedia

GET /api/ext/v1/folders

Folders

Permission: content:read

Parameters

Name	In	Type	Required
page	query	integer	—
pageSize	query	integer	—

Responses: 200 ExtPageOfExtFolder

POST /api/ext/v1/folders

New folder

Permission: content:write

Body: ExtFolderRequest

Responses: 201 ExtFolder · 400 Bad Request

PUT /api/ext/v1/folders/{id}

Renames a folder

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: ExtFolderRequest

Responses: 200 ExtFolder · 400 Bad Request

DELETE /api/ext/v1/folders/{id}

Deletes an empty folder

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 204 No Content

Playlists

GET /api/ext/v1/playlists

Playlists

Permission: content:read

Parameters

Name	In	Type	Required
page	query	integer	—
pageSize	query	integer	—

Responses: 200 ExtPageOfExtPlaylistSummary

POST /api/ext/v1/playlists

A playlist and its items in one request

Permission: content:write

Body: ExtPlaylistRequest

Responses: 201 ExtPlaylist · 400 Bad Request

GET /api/ext/v1/playlists/{id}

A playlist and its items

Permission: content:read

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 ExtPlaylist

PUT /api/ext/v1/playlists/{id}

Writes the whole playlist; screens update right away

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: ExtPlaylistRequest

Responses: 200 ExtPlaylist · 400 Bad Request

DELETE /api/ext/v1/playlists/{id}

Moves to the trash; removed from screens and rules

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 204 No Content

Schedule

GET /api/ext/v1/schedule

Rules in priority order

Permission: content:read

Responses: 200 ExtScheduleRule[]

PUT /api/ext/v1/schedule

Writes all rules in order (the first rule has the highest priority)

Permission: content:write

Body: ExtScheduleRequest

Responses: 200 ExtScheduleRule[] · 400 Bad Request

POST /api/ext/v1/schedule/impact

Dry run: the effect of this rule list on the next 7 days and opening hours left empty

Permission: content:read

Body: ExtScheduleRequest

Responses: 200 ExtScheduleImpact · 400 Bad Request

Emergency alerts

GET /api/ext/v1/alerts

Active and recent alerts

Permission: content:read

Responses: 200 ExtAlert[]

POST /api/ext/v1/alerts

Full-screen alert on the chosen screens right away

Permission: content:write

Body: ExtAlertRequest

Responses: 201 ExtAlert · 400 Bad Request

POST /api/ext/v1/alerts/{id}/end

Ends an alert

Permission: content:write

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 ExtAlert

Reports

GET /api/ext/v1/reports/plays

Proof-of-play report (from, to: yyyy-MM-dd; optional screenId)

Permission: reports:read

Parameters

Name	In	Type	Required
from	query	date	yes
to	query	date	yes
screenId	query	uuid	—

Responses: 200 ExtPlayReport

GET /api/ext/v1/reports/plays.csv

Proof-of-play report as CSV

Permission: reports:read

Parameters

Name	In	Type	Required
from	query	date	yes
to	query	date	yes
screenId	query	uuid	—
lang	query	string	—

Responses: 200 OK

GET /api/ext/v1/reports/uptime

Uptime report

Permission: reports:read

Parameters

Name	In	Type	Required
from	query	date	yes
to	query	date	yes
screenId	query	uuid	—

Responses: 200 ExtUptimeReport

GET /api/ext/v1/reports/uptime.csv

Uptime report as CSV

Permission: reports:read

Parameters

Name	In	Type	Required
from	query	date	yes
to	query	date	yes
screenId	query	uuid	—
lang	query	string	—

Responses: 200 OK

Webhooks

GET /api/ext/v1/webhooks

Webhook addresses

Permission: webhooks:manage

Responses: 200 WebhookResponse[]

POST /api/ext/v1/webhooks

New address (at most 5); the signing secret is returned only in this response

Permission: webhooks:manage

Body: WebhookRequest

Responses: 201 WebhookSecretResponse · 400 Bad Request

PUT /api/ext/v1/webhooks/{id}

Address, events and on/off; turning a paused address back on resets its failure count

Permission: webhooks:manage

Parameters

Name	In	Type	Required
id	path	uuid	yes

Body: WebhookRequest

Responses: 200 WebhookResponse · 400 Bad Request

DELETE /api/ext/v1/webhooks/{id}

Deletes a webhook address

Permission: webhooks:manage

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 204 No Content

POST /api/ext/v1/webhooks/{id}/rotate-secret

New signing secret; the old one stops working immediately

Permission: webhooks:manage

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 WebhookSecretResponse

POST /api/ext/v1/webhooks/{id}/test

Queues a webhook.test event

Permission: webhooks:manage

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 202 WebhookDeliveryResponse

GET /api/ext/v1/webhooks/{id}/deliveries

Deliveries of the last 7 days

Permission: webhooks:manage

Parameters

Name	In	Type	Required
id	path	uuid	yes

Responses: 200 WebhookDeliveryResponse[]

Schemas

ExtAlert

Field	Type	Required
id	uuid	yes
title	string	yes
message	string	yes
tone	danger | info	yes
target	all | locations | tags | screens	yes
targetIds	uuid[]	yes
tags	string[]	yes
startsAt	date-time	yes
endsAt	date-time | null	yes
endedAt	date-time | null	yes
active	boolean	yes

ExtAlertRequest

Field	Type	Required
title	string	yes
message	string | null	yes
tone	danger | info	yes
target	all | locations | tags | screens	yes
targetIds	uuid[] | null	—
tags	string[] | null	—
endsAt	date-time | null	—

ExtApiKey

Field	Type	Required
id	uuid	yes
name	string	yes
scopes	string[]	yes
expiresAt	date-time | null	yes

ExtCommand

Field	Type	Required
id	uuid	yes
screenId	uuid	yes
type	string	yes
status	pending | delivered | succeeded | failed | unsupported | expired	yes
createdAt	date-time	yes
expiresAt	date-time	yes
finishedAt	date-time | null	yes
message	string | null	yes

ExtCommandRequest

Field	Type	Required
type	string	yes
volume	integer | null	—

ExtDevice

Field	Type	Required
platform	android | web | webos | tizen | windows	yes
manufacturer	string | null	yes
model	string | null	yes
osVersion	string | null	yes
playerVersion	string	yes
online	boolean	yes
lastSeenAt	date-time | null	yes
displayWidth	integer | null	yes
displayHeight	integer | null	yes
nowPlaying	any	yes
availableCommands	string[]	yes

ExtFolder

Field	Type	Required
id	uuid	yes
name	string	yes
mediaCount	integer	yes

ExtFolderRequest

Field	Type	Required
name	string	yes

ExtLocation

Field	Type	Required
id	uuid	yes
name	string	yes
address	string | null	yes
city	string | null	yes
timeZone	string | null	yes
createdAt	date-time	yes

ExtMe

Field	Type	Required
tenant	ExtRef	yes
key	ExtApiKey	yes

ExtMedia

Field	Type	Required
id	uuid	yes
name	string	yes
type	image | video	yes
status	uploading | processing | ready | failed	yes
folderId	uuid | null	yes
contentType	string	yes
sizeBytes	integer	yes
width	integer | null	yes
height	integer | null	yes
durationMs	integer | null	yes
url	string | null	yes
thumbnailUrl	string | null	yes
failureCode	string | null	yes
source	upload | ai	yes
createdAt	date-time	yes

ExtMediaUpdate

Field	Type	Required
name	string	yes
folderId	uuid | null	yes

ExtNowPlaying

Field	Type	Required
mediaId	uuid	yes
name	string	yes

ExtOpenHours

Field	Type	Required
days	integer[]	yes
open	string	yes
close	string	yes

ExtPageOfExtFolder

Field	Type	Required
items	ExtFolder[]	yes
page	integer	yes
pageSize	integer	yes
total	integer	yes

ExtPageOfExtLocation

Field	Type	Required
items	ExtLocation[]	yes
page	integer	yes
pageSize	integer	yes
total	integer	yes

ExtPageOfExtMedia

Field	Type	Required
items	ExtMedia[]	yes
page	integer	yes
pageSize	integer	yes
total	integer	yes

ExtPageOfExtPlaylistSummary

Field	Type	Required
items	ExtPlaylistSummary[]	yes
page	integer	yes
pageSize	integer	yes
total	integer	yes

ExtPageOfExtScreen

Field	Type	Required
items	ExtScreen[]	yes
page	integer	yes
pageSize	integer	yes
total	integer	yes

ExtPlayContent

Field	Type	Required
kind	media | template | widget	yes
contentId	string	yes
name	string | null	yes
plays	integer	yes
seconds	integer	yes
screens	integer	yes

ExtPlayReport

Field	Type	Required
from	date	yes
to	date	yes
plays	integer	yes
seconds	integer	yes
contents	ExtPlayContent[]	yes
screens	ExtPlayScreen[]	yes

ExtPlayScreen

Field	Type	Required
screenId	uuid	yes
name	string	yes
plays	integer	yes
seconds	integer	yes

ExtPlaylist

Field	Type	Required
id	uuid	yes
name	string	yes
shuffle	boolean	yes
items	ExtPlaylistItem[]	yes
updatedAt	date-time	yes

ExtPlaylistItem

Field	Type	Required
id	uuid	yes
kind	media | design | widget | plugin	yes
durationSeconds	integer	yes
validFrom	date | null	yes
validTo	date | null	yes
mediaId	uuid | null	yes
designId	uuid | null	yes
widget	any	yes
pluginCode	string | null	yes

ExtPlaylistItemRequest

Field	Type	Required
durationSeconds	integer	yes
mediaId	uuid | null	—
designId	uuid | null	—
widget	any	—
pluginCode	string | null	—
validFrom	date | null	—
validTo	date | null	—

ExtPlaylistRequest

Field	Type	Required
name	string	yes
shuffle	boolean	yes
items	ExtPlaylistItemRequest[]	yes

ExtPlaylistSummary

Field	Type	Required
id	uuid	yes
name	string	yes
shuffle	boolean	yes
itemCount	integer	yes
totalSeconds	integer	yes
updatedAt	date-time	yes

ExtRef

Field	Type	Required
id	uuid	yes
name	string	yes

ExtScheduleGap

Field	Type	Required
screenId	uuid	yes
screen	string	yes
day	integer	yes
at	string	yes
hours	number	yes
isNew	boolean	yes

ExtScheduleImpact

Field	Type	Required
affectedScreens	integer	yes
changedHours	number	yes
gaps	ExtScheduleGap[]	yes

ExtScheduleRequest

Field	Type	Required
rules	ExtScheduleRuleRequest[]	yes

ExtScheduleRule

Field	Type	Required
id	uuid	yes
name	string	yes
playlist	ExtRef	yes
days	integer[]	yes
start	string | null	yes
end	string | null	yes
validFrom	date | null	yes
validTo	date | null	yes
target	all | screens | tag	yes
screenIds	uuid[]	yes
tag	string | null	yes
priority	integer	yes

ExtScheduleRuleRequest

Field	Type	Required
name	string	yes
playlistId	uuid	yes
days	integer[]	yes
start	string | null	—
end	string | null	—
validFrom	date | null	—
validTo	date | null	—
target	all | screens | tag	—
screenIds	uuid[] | null	—
tag	string | null	—

ExtScreen

Field	Type	Required
id	uuid	yes
name	string	yes
location	any	yes
defaultPlaylist	any	yes
orientation	landscape | portrait	yes
rotation	integer	yes
fit	contain | cover | fill | auto	yes
muted	boolean	yes
kiosk	boolean	yes
tags	string[]	yes
openHours	ExtOpenHours[] | null	yes
device	any	yes
createdAt	date-time	yes

ExtScreenSettings

Field	Type	Required
name	string	yes
locationId	uuid | null	yes
defaultPlaylistId	uuid | null	yes
orientation	landscape | portrait	yes
rotation	integer	yes
fit	contain | cover | fill | auto	yes
muted	boolean	yes
kiosk	boolean	yes
tags	string[] | null	yes
openHours	ExtOpenHours[] | null	yes

ExtScreenshot

Field	Type	Required
url	string	yes
takenAt	date-time	yes

ExtUpload

Field	Type	Required
media	ExtMedia	yes
uploadUrl	string	yes
headers	{ [key]: string }	yes
expiresAt	date-time	yes

ExtUploadRequest

Field	Type	Required
fileName	string	yes
contentType	string	yes
sizeBytes	integer	yes
folderId	uuid | null	yes

ExtUptimeDay

Field	Type	Required
date	date	yes
onlineSeconds	integer	yes
openSeconds	integer	yes

ExtUptimeReport

Field	Type	Required
from	date	yes
to	date	yes
onlineSeconds	integer	yes
openSeconds	integer	yes
screens	ExtUptimeScreen[]	yes

ExtUptimeScreen

Field	Type	Required
screenId	uuid	yes
name	string	yes
onlineSeconds	integer	yes
openSeconds	integer	yes
days	ExtUptimeDay[]	yes

WebhookDeliveryResponse

Field	Type	Required
id	uuid	yes
event	string	yes
status	pending | succeeded | failed	yes
attempts	integer	yes
lastStatusCode	integer | null	yes
lastError	string | null	yes
createdAt	date-time	yes
deliveredAt	date-time | null	yes
nextAttemptAt	date-time | null	yes

WebhookRequest

Field	Type	Required
url	string	yes
description	string | null	yes
events	string[]	yes
enabled	boolean	—

WebhookResponse

Field	Type	Required
id	uuid	yes
url	string	yes
description	string | null	yes
events	string[]	yes
enabled	boolean	yes
disabledAt	date-time | null	yes
consecutiveFailures	integer	yes
createdAt	date-time	yes

WebhookSecretResponse

Field	Type	Required
webhook	WebhookResponse	yes
secret	string	yes

WidgetConfig

Field	Type	Required
kind	clock | weather | rates	yes
placeId	string | null	—