Introduction

Signage API

Overview

Organisation-scoped screens, pages, assets, and player devices. Screens may link to Directory via optional locationId.

Integration guide: Signage service docs

OpenAPI v0.1.0 · source openapi/signage.json

OpenAPI 3.0.0 · v0.1.0 · 40 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/health"

Unauthenticated liveness probe. Does not verify D1, R2, or JWT configuration.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/health"

Unauthenticated liveness probe. Alias of GET /health.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Auth

Operator login. Directory owns credentials when the DIRECTORY binding is set.

post/v1/auth/login

Operator login

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/auth/login"

Proxies email/password to Directory when the DIRECTORY binding is configured and returns the Directory JWT plus the local operator profile. Local password validation is only available in non-production environments without Directory (tests and seeds).

Operation ID: login

Request body(required)

application/jsonLoginRequest

Responses

200
JWT, actor claims, and operator profile
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Dev

Development-only helpers. Disabled when ENVIRONMENT=production.

post/v1/dev/seed

Seed demo account data

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/dev/seed"

Creates the Acme demo account, operator, shop, screens, and pages when they do not already exist. admin only. Disabled when `ENVIRONMENT=production` (403 FORBIDDEN).

Operation ID: seedDemoData

Responses

200
Seeded account id, demo email, and demo password
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Dashboard

Organisation screen and device counts.

get/v1/dashboard

Account dashboard counts

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/dashboard"

Returns screen and device totals for the caller's account: online/offline screens, pending updates, errors, and unclaimed devices. Any operator role may read.

Operation ID: getDashboard

Responses

200
Aggregated screen and device counts
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Screens

Logical displays (playlist target). Optional locationId links Directory.

get/v1/screens

List screens

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/screens"

Returns screens in the caller's account, each with the assigned `deviceId` if any. Archived screens are omitted unless `archived=true`. Optional `locationId` filter. Any operator role may read.

Operation ID: listScreens

Parameters

Name	In	Type	Description
archived	query	string	If `true`, include archived screens. Default omits archived screens.
locationId	query	string (uuid)	If set, only return screens linked to this Directory location UUID.

Responses

200
Screens in the account
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/screens

Create screen

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/screens"

Creates a logical display (screen). Defaults: landscape, 1920×1080, no page. Optional Directory `locationId` links the screen to a catalogue location.

Operation ID: createScreen

Request body(required)

application/jsonScreenCreate

Responses

201
Created screen
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/screens/{id}

Get screen

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/screens/example-id"

Returns one screen including the assigned `deviceId` when a player is paired. Archived screens are still returned if the id is known.

Operation ID: getScreen

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Screen id in the caller's account

Responses

200
Screen
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/screens/{id}

Update screen

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/signage/v1/screens/example-id"

Updates name, location, page, orientation, target resolution, or archived flag. Omitted fields are unchanged.

Operation ID: updateScreen

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Screen id in the caller's account

Request body(required)

application/jsonobject

Responses

200
Updated screen
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/screens/{id}

Delete screen

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/screens/example-id"

Permanently removes a screen, clears device assignments for that screen, and deletes publication history. Devices remain claimed but unassigned.

Operation ID: deleteScreen

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Screen id in the caller's account

Responses

200
Screen deleted
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Publishing

Push page manifests to screens for player sync.

post/v1/publish/screens/{id}

Publish screen page

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/publish/screens/example-id"

Builds a content-addressed manifest for the screen's page and bumps configuration/content versions. Devices pick this up on the next sync. Fails if no page is assigned.

Operation ID: publishScreen

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Screen id in the caller's account

Responses

200
Published manifest and versions
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Pages

HTML/CSS layouts and page-local assets for screens.

get/v1/pages

List pages

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/pages"

Returns non-archived pages in the caller's account, each with `assetHashes` extracted from HTML/CSS. Any operator role may read.

Operation ID: listPages

Responses

200
Pages in the account
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/pages

Create page

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/pages"

Creates a page. HTML/CSS default to empty strings. Referenced asset hashes are linked when present in the account.

Operation ID: createPage

Request body(required)

application/jsonPageCreate

Responses

201
Created page
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/pages/{id}

Get page

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/pages/example-id"

Returns one page including HTML, CSS, and referenced asset hashes. Archived pages are still returned if the id is known.

Operation ID: getPage

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Page id in the caller's account

Responses

200
Page with asset hashes
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/pages/{id}

Update page

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/signage/v1/pages/example-id"

Updates name, HTML, CSS, or archived flag. Changing HTML/CSS re-links referenced assets.

Operation ID: updatePage

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Page id in the caller's account

Request body(required)

application/jsonobject

Responses

200
Updated page
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/pages/{id}

Delete page

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/pages/example-id"

Permanently removes a page and its version history. Screens that referenced the page have `pageId` cleared.

Operation ID: deletePage

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Page id in the caller's account

Responses

200
Page deleted
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Device runtime

Player enrollment, token exchange, sync manifest, and heartbeat.

post/v1/devices/enroll

Enroll a display device

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/enroll"

Creates an unclaimed Pi identity, pairing code, device secret, and JWT. The device cannot choose an account or screen. No bearer token is required. Store `deviceSecret`; it is not returned again. `/v1/devices/register` is a legacy alias of this path.

Operation ID: enrollDevice

Request body(required)

application/jsonDeviceEnrollRequest

Responses

201
Device id, secret, pairing code, and JWT
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/device/enroll

Enroll a display device

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/device/enroll"

Operation ID: enrollDeviceAlias

Request body(required)

application/jsonDeviceEnrollRequest

Responses

201
Device id, secret, pairing code, and JWT
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/devices/register

Enroll a display device

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/register"

Operation ID: enrollDeviceAlias2

Request body(required)

application/jsonDeviceEnrollRequest

Responses

201
Device id, secret, pairing code, and JWT
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/device/register

Enroll a display device

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/device/register"

Operation ID: enrollDeviceAlias3

Request body(required)

application/jsonDeviceEnrollRequest

Responses

201
Device id, secret, pairing code, and JWT
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/devices/token

Exchange device credentials for a JWT

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/token"

Returns a fresh display_device JWT for `deviceId` + `deviceSecret`. Revoked devices return 401 UNAUTHORIZED. No bearer token is required.

Operation ID: mintDeviceToken

Request body(required)

application/jsonDeviceTokenRequest

Responses

200
Device JWT and current status
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/device/token

Exchange device credentials for a JWT

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/device/token"

Returns a fresh display_device JWT for `deviceId` + `deviceSecret`. Revoked devices return 401 UNAUTHORIZED. No bearer token is required. Alias of `/v1/devices/token`.

Operation ID: mintDeviceTokenAlias

Request body(required)

application/jsonDeviceTokenRequest

Responses

200
Device JWT and current status
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/device/sync

Sync device content (GET)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/device/sync"

Same as POST /v1/device/sync but versions are query parameters. Requires a display_device JWT. Prefer POST for telemetry.

Operation ID: syncDeviceGet

Parameters

Name	In	Type	Description
configurationVersion	query	string	Device's current configuration version. Defaults to 0.
contentVersion	query	string	Device's current content version. Defaults to 0.
softwareVersion	query	string	Optional software version reported by the device.

Responses

200
Unchanged ping or full published manifest
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/device/sync

Sync device content

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/device/sync"

Pi poll endpoint. Requires a display_device JWT. Reports telemetry and returns either a compact unchanged payload or a full manifest when configuration/content versions differ. Unclaimed devices receive a refreshed pairing code.

Operation ID: syncDevice

Request body(required)

application/jsonSyncRequest

Responses

200
Unchanged ping or full published manifest
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/devices/sync

Sync device content (GET)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/sync"

Same as POST /v1/device/sync but versions are query parameters. Requires a display_device JWT. Prefer POST for telemetry. Alias of `/v1/device/sync`.

Operation ID: syncDeviceGetAlias

Parameters

Name	In	Type	Description
configurationVersion	query	string	Device's current configuration version. Defaults to 0.
contentVersion	query	string	Device's current content version. Defaults to 0.
softwareVersion	query	string	Optional software version reported by the device.

Responses

200
Unchanged ping or full published manifest
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/devices/sync

Sync device content

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/sync"

Operation ID: syncDeviceAlias

Request body(required)

application/jsonSyncRequest

Responses

200
Unchanged ping or full published manifest
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/device/heartbeat

Device heartbeat

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/device/heartbeat"

Records telemetry the same way as sync, then returns current UI status and versions without a manifest. Requires a display_device JWT.

Operation ID: deviceHeartbeat

Request body(required)

application/jsonSyncRequest

Responses

200
Current device status
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/devices/heartbeat

Device heartbeat

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/heartbeat"

Records telemetry the same way as sync, then returns current UI status and versions without a manifest. Requires a display_device JWT. Alias of `/v1/device/heartbeat`.

Operation ID: deviceHeartbeatAlias

Request body(required)

application/jsonSyncRequest

Responses

200
Current device status
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/device/status

Device status

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/device/status"

Returns UI status and published versions for the calling device. Requires a display_device JWT. Does not update last-seen.

Operation ID: getDeviceStatus

Responses

200
Current device status
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/devices/status

Device status

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/status"

Returns UI status and published versions for the calling device. Requires a display_device JWT. Does not update last-seen. Alias of `/v1/device/status`.

Operation ID: getDeviceStatusAlias

Responses

200
Current device status
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/device/configuration

Device configuration

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/device/configuration"

Returns screen assignment, versions, and poll interval for the calling device. Requires a display_device JWT.

Operation ID: getDeviceConfiguration

Responses

200
Assignment and poll interval
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/devices/configuration

Device configuration

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/configuration"

Returns screen assignment, versions, and poll interval for the calling device. Requires a display_device JWT. Alias of `/v1/device/configuration`.

Operation ID: getDeviceConfigurationAlias

Responses

200
Assignment and poll interval
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/device/assets/{hash}

Fetch asset bytes

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/device/assets/example-id"

Returns content-addressed asset bytes by SHA-256 for operators (account-scoped) or the calling display_device. Response is immutable (`Cache-Control: public, max-age=31536000`).

Operation ID: getAsset

Parameters

Name	In	Type	Description
hash*	path	string	SHA-256 hex digest of the asset bytes

Responses

200
Raw asset bytes. Content-Type is the stored MIME type.
application/octet-stream
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/devices/assets/{hash}

Fetch asset bytes

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/assets/example-id"

Returns content-addressed asset bytes by SHA-256 for operators (account-scoped) or the calling display_device. Response is immutable (`Cache-Control: public, max-age=31536000`). Alias of `/v1/device/assets/{hash}`.

Operation ID: getAssetAlias

Parameters

Name	In	Type	Description
hash*	path	string	SHA-256 hex digest of the asset bytes

Responses

200
Raw asset bytes. Content-Type is the stored MIME type.
application/octet-stream
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Devices

Claimed display players linked to the organisation.

get/v1/devices

List linked devices

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices"

Returns claimed devices in the caller's account (excludes unclaimed enrollments). Status is a UI value derived from last-seen. Any operator role may read.

Operation ID: listDevices

Responses

200
Linked devices in the account
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/devices/{id}

Get device

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/example-id"

Returns one linked device in the caller's account. Unclaimed devices are not visible.

Operation ID: getDevice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Device id in the caller's account

Responses

200
Device
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/devices/{id}

Update device

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/example-id"

Updates device name or assigned screen. Assigning a screen already paired to another device revokes the previous device. member is forbidden.

Operation ID: updateDevice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Device id in the caller's account

Request body(required)

application/jsonDevicePatch

Responses

200
Updated device
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/devices/{id}

Remove device

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/devices/example-id"

Revokes device credentials, clears the screen assignment, and marks the device removed. member is forbidden. Subsequent token or sync calls fail.

Operation ID: deleteDevice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Device id in the caller's account

Responses

200
Device removed
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/devices/claim

Claim a device

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/signage/v1/devices/claim"

Links an unclaimed device to the account using the on-screen pairing code. Creates a screen if `screenId` is omitted. member is forbidden. Expired or already-claimed codes fail.

Operation ID: claimDevice

Request body(required)

application/jsonClaimDeviceRequest

Responses

200
Claimed device
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically BAD_REQUEST or VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
404
The requested resource was not found. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical cause: device already claimed.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Audit

Signage audit trail derived from device and operator events.

get/v1/audit

Signage audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/signage/v1/audit"

Recent shop, screen, page, and device changes for the JWT organisation.

Operation ID: listSignageAudit

Responses

200
Audit events
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member, display_device.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: invalid body, expired pairing code, missing page on publish.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json