Endpoints

GET /layout/{layoutId}

Discover the controls on the active page of a layout.

Request

GET /layout/{layoutId}
x-api-key: YOUR_API_KEY

Response

{
  "layoutId": "abc123",
  "activePageId": "page_1",
  "controls": [
    {
      "lid": 1,
      "address": "/001",
      "type": "Button",
      "props": { "label": "Cheer" }
    },
    {
      "lid": 3,
      "address": "/003",
      "type": "Index",
      "props": { "label": "Vote" },
      "options": [
        { "index": 0, "label": "Option A" },
        { "index": 1, "label": "Option B" }
      ]
    }
  ],
  "destinationCount": 1
}

Fields

Field	Type	Description
layoutId	string	The layout identifier
activePageId	string	Currently active page
controls	array	Controls on the active page
controls[].lid	number	Local ID — used when sending actions
controls[].address	string	OSC address (e.g. /001)
controls[].type	string	Control type (see Control Types)
controls[].props	object	Display properties (label, etc.)
controls[].options	array?	For Index controls — the selectable options
destinationCount	number	Number of connected output displays

---

POST /token

Create an audience token for sending actions.

Request

POST /token
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "layoutId": "YOUR_LAYOUT_ID"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Errors

Status	Reason
400	Missing or invalid layoutId
401	Invalid or missing API key

---

POST /action

Send a control action to the live output.

Request

POST /action
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "layoutId": "YOUR_LAYOUT_ID",
  "lid": 1,
  "type": "Button",
  "value": null
}

Fields

Field	Type	Required	Description
layoutId	string	Yes	Target layout
lid	number	Yes	Control local ID (from layout discovery)
type	string	Yes	Must match the control’s type
value	varies	Depends	Value for the action (see below)

Value by type

Type	Value	Example
Button	omit or null	"value": null
Slider	float 0–1	"value": 0.75
Toggle	boolean	"value": true
Index	integer (0-based)	"value": 2
String	string	"value": "hello"
XYPad	[x, y] floats 0–1	"value": [0.5, 0.3]

Response

{
  "ok": true
}

Errors

Status	Reason
400	Missing fields, invalid type, or control not found
401	Missing or invalid token