Overview
MXMZ is a set of services, each with its own base URL and its own job. An endpoint from one service does not work against another.
Graphics APIRundowns, playlists and live control. What an operator does, from code.
Package ManagerGraphics packages and their released versions.
Playout ServiceOutputs over REST, and on air control over a websocket.
Websocket messagesClaim an output, load a package, animate graphics and push live data.
Regions
MXMZ runs as two separate regions. The API is identical in both. Only the hostname differs: North America carries .use2, Europe does not.
| Service | North America | Europe |
|---|---|---|
| Graphics API | https://graphics-api.use2.mxmz.io | https://graphics-api.mxmz.io |
| Package Manager | https://package-manager-api.use2.mxmz.io | https://package-manager-api.mxmz.io |
| Playout Service | https://playout-service.use2.mxmz.io | https://playout-service.mxmz.io |
Credentials, outputs, rundowns and packages belong to the region they were created in. A key from one region does not authenticate against the other, and on the websocket that mismatch shows up as a bare connection error.
Authentication
Every REST request carries two headers: your API Client ID and your API Secret as a bearer token. Both are issued per account by MXMZ Support, at support@mxmzmedia.com.
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/live' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Request and response bodies are JSON. Treat the Client ID and Secret as credentials: they grant control of live output.
| Status | Meaning |
|---|---|
| 200 201 204 | Success. 201 when something was created, 204 when there is no body. |
| 400 | The input is invalid or a required field is missing. |
| 401 | The token is missing or invalid. Check that the key matches the region. |
| 403 | The account authenticated but lacks permission for this action. |
| 404 | The resource does not exist in this workspace or region. |
| 409 | The rundown is locked and cannot be changed or deleted. |
Prefer to try calls in the browser? The interactive API docs include a test client.
No endpoint matches that filter.
Graphics API
The Operator side of the platform: rundowns, playlists and live control of the graphics in them, including quick graphics and match control.
Base URL https://graphics-api.use2.mxmz.io OpenAPI document
Controls
POST/api/v1/controls/graphic/live/inAnimate graphic live
Animates a graphic on the live output channel for broadcast
Request body
playlistGraphicId | string | required |
Responses
- 200 Graphic live animation started
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/graphic/live/in' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"playlistGraphicId": "string"
}'POST/api/v1/controls/graphic/live/outHide graphic live
Hides the currently displayed graphic on the live output
Request body
playlistGraphicId | string | required |
Responses
- 200 Graphic live hidden successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/graphic/live/out' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"playlistGraphicId": "string"
}'POST/api/v1/controls/graphic/live/updateUpdate graphic live
Updates the currently displayed graphic on the live output with new data or state
Request body
playlistGraphicId | string | required | |
action | string | required |
Responses
- 200 Graphic live updated successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/graphic/live/update' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"playlistGraphicId": "string",
"action": "string"
}'POST/api/v1/controls/rundown/{rundownId}/graphic/toggleToggle graphic in match control of rundown
Toggles the visibility of a graphic in the match control system for the specified rundown
Path parameters
rundownId | string | required | Rundown UUID |
Request body
An empty JSON object.
Responses
- 200 Match control graphic toggled successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/rundown/{rundownId}/graphic/toggle' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{}'GET/api/v1/controls/output/{outputId}/quickGraphicGet status of all quick graphics
Retrieves the current status of all quick graphics configured for the specified output
Path parameters
outputId | string | required | Output UUID |
Responses
- 200 Quick graphics status retrieved successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/quickGraphic' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}Get status of quick graphic by ID
Retrieves the current status of a specific quick graphic using output ID and graphic index
Path parameters
outputId | string | required | Output UUID |
quickGraphicIndex | number | required | Quick graphic index number |
Responses
- 200 Quick graphic status retrieved successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/toggleToggle quick graphic by ID
Toggles the visibility of a specific quick graphic on or off
Path parameters
outputId | string | required | Output UUID |
quickGraphicIndex | number | required | Quick graphic index number |
Responses
- 200 Quick graphic toggled successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/toggle' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/inShow quick graphic by ID
Displays a specific quick graphic on the output
Path parameters
outputId | string | required | Output UUID |
quickGraphicIndex | number | required | Quick graphic index number |
Responses
- 200 Quick graphic shown successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/in' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/outHide quick graphic by ID
Hides a specific quick graphic from the output
Path parameters
outputId | string | required | Output UUID |
quickGraphicIndex | number | required | Quick graphic index number |
Responses
- 200 Quick graphic hidden successfully
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/quickGraphic/{quickGraphicIndex}/out' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}Get clock by output
Retrieves the current clock state for a specific output and clock type, including whether it is running, start time, and clock direction.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 Clock state retrieved successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/startStart clock on output
Starts a specific clock (match, shot, extra time) for an output. Records the user who initiated the action.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 Clock started successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/start' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/stopStop clock on output
Stops a running clock for an output. Records the user who initiated the action.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 Clock stopped successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/stop' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/{contestantIndex}/addClock/{time}Add clock time to contestant
Adds a specific amount of time to a contestant clock (e.g., timeout clock). Optionally specify the time to add, otherwise uses default.
Path parameters
outputId | string | required | |
clockType | string | required | |
contestantIndex | number | required | |
time | number | required |
Responses
- 200 Clock time added successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/{contestantIndex}/addClock/{time}' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/addSecondAdd one second to clock
Increments the specified clock by one second for an output. Useful for manual clock adjustments.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 One second added to clock successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/addSecond' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/addFiveSecondsAdd five seconds to clock
Increments the specified clock by five seconds for an output. Useful for quick manual clock adjustments.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 Five seconds added to clock successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/addFiveSeconds' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/removeSecondRemove one second from clock
Decrements the specified clock by one second for an output. Useful for manual clock corrections.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 One second removed from clock successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/removeSecond' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/removeFiveSecondsRemove five seconds from clock
Decrements the specified clock by five seconds for an output. Useful for quick manual clock corrections.
Path parameters
outputId | string | required | |
clockType | string | required |
Responses
- 200 Five seconds removed from clock successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/clock/{clockType}/removeFiveSeconds' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/controls/output/{outputId}/matchcontrolGet match control data
Retrieves the complete match control data for an output, including scores, clocks, cards, and all match state.
Path parameters
outputId | string | required |
Responses
- 200 Match control data retrieved successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/score/{contestantIndex}/addGoalAdd goal to contestant
Increments the score for a specific contestant (team). Records the user who scored the goal.
Path parameters
outputId | string | required | |
contestantIndex | number | required |
Responses
- 200 Goal added successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/score/{contestantIndex}/addGoal' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/score/{contestantIndex}/removeGoalRemove goal from contestant
Decrements the score for a specific contestant (team). Records the user who removed the goal.
Path parameters
outputId | string | required | |
contestantIndex | number | required |
Responses
- 200 Goal removed successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/score/{contestantIndex}/removeGoal' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/cards/{contestantIndex}/{cardType}/addAdd card to contestant
Adds a card (yellow or red) to a specific contestant. Records the user who issued the card.
Path parameters
outputId | string | required | |
contestantIndex | number | required | |
cardType | string | required |
Responses
- 200 Card added successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/cards/{contestantIndex}/{cardType}/add' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/cards/{contestantIndex}/{cardType}/removeRemove card from contestant
Removes a card (yellow or red) from a specific contestant. Records the user who removed the card.
Path parameters
outputId | string | required | |
contestantIndex | number | required | |
cardType | string | required |
Responses
- 200 Card removed successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/cards/{contestantIndex}/{cardType}/remove' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/videoReferral/{contestantIndex}/addAdd video referral to contestant
Adds a video referral (challenge/review) to a specific contestant. Records the user who added the referral.
Path parameters
outputId | string | required | |
contestantIndex | number | required |
Responses
- 200 Video referral added successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/videoReferral/{contestantIndex}/add' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/videoReferral/{contestantIndex}/removeRemove video referral from contestant
Removes a video referral (challenge/review) from a specific contestant. Records the user who removed the referral.
Path parameters
outputId | string | required | |
contestantIndex | number | required |
Responses
- 200 Video referral removed successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/videoReferral/{contestantIndex}/remove' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/controls/output/{outputId}/matchcontrol/graphicGet match control graphics
Retrieves all available match control graphics for an output, including their control IDs and current states.
Path parameters
outputId | string | required |
Responses
- 200 Match control graphics retrieved successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/graphic' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/graphic/{controlId}/inAnimate match control graphic in
Animates a match control graphic in (shows it) using its control ID. For example, use "clock" to show the clock graphic, or "extraTime" to show the extra time graphic.
Path parameters
outputId | string | required | |
controlId | string | required |
Responses
- 200 Graphic animated in successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/graphic/{controlId}/in' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/graphic/{controlId}/outAnimate match control graphic out
Animates a match control graphic out (hides it) using its control ID. For example, use "clock" to hide the clock graphic, or "extraTime" to hide the extra time graphic.
Path parameters
outputId | string | required | |
controlId | string | required |
Responses
- 200 Graphic animated out successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/graphic/{controlId}/out' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/controls/output/{outputId}/matchcontrol/configUpdate match control configuration
Updates the configuration of match control for an output, including period settings, clock directions, and other match parameters.
Path parameters
outputId | string | required |
Request body
period | object | required | |
hasShootOut | boolean | required |
Responses
- 200 Match control configuration updated successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/config' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"period": {},
"hasShootOut": true
}'POST/api/v1/controls/output/{outputId}/matchcontrol/config/period/addAdd period to match control
Adds a new period (quarter, half, etc.) to the match control configuration. Records the user who added the period.
Path parameters
outputId | string | required |
Responses
- 200 Period added successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/config/period/add' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/controls/output/{outputId}/matchcontrol/config/period/removeRemove period from match control
Removes the last period from the match control configuration. Records the user who removed the period.
Path parameters
outputId | string | required |
Responses
- 200 Period removed successfully
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/controls/output/{outputId}/matchcontrol/config/period/remove' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Graphic Packages
GET/api/v1/graphicpackagesGet all graphic packages
Retrieves a list of all graphic packages. Optionally includes deprecated packages with filter parameter.
Query parameters
filter | object | required |
Responses
- 200 Successfully retrieved all graphic packages
- 401 Unauthorized - Invalid or missing authentication token
Response shape
[
null
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/graphicpackages?filter=' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/graphicpackages/{id}Get graphic package by ID
Retrieves detailed information about a specific graphic package by ID.
Path parameters
id | string | required | ID of the graphic package to retrieve |
Responses
- 200 Successfully retrieved graphic package
- 401 Unauthorized - Invalid or missing authentication token
- 404 Not Found - Resource does not exist
Response shape
{
"id": 1,
"uuid": "660e8400-e29b-41d4-a716-446655440000",
"name": "Sports Package 2024",
"ref": "sports-2024",
"version": "2.0.0",
"description": "Complete sports graphics package",
"cdnUrl": "https://cdn.mxmz.io/graphicpackages/sports-2024/",
"deprecated": false,
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:00:00Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/graphicpackages/{id}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/graphicpackages/ref/{id}Get graphic package by reference
Retrieves a graphic package by its reference identifier (ref) instead of ID.
Path parameters
id | string | required | Reference identifier of the graphic package |
Responses
- 200 Successfully retrieved graphic package
- 401 Unauthorized - Invalid or missing authentication token
- 404 Not Found - Resource does not exist
Response shape
{
"id": 1,
"uuid": "660e8400-e29b-41d4-a716-446655440000",
"name": "Sports Package 2024",
"ref": "sports-2024",
"version": "2.0.0",
"description": "Complete sports graphics package",
"cdnUrl": "https://cdn.mxmz.io/graphicpackages/sports-2024/",
"deprecated": false
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/graphicpackages/ref/{id}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/graphicpackages/{id}/graphicsGet all graphics in a package
Retrieves all graphics that belong to a specific graphic package.
Path parameters
id | string | required | UUID of the graphic package |
Responses
- 200 Successfully retrieved graphics in package
- 401 Unauthorized - Invalid or missing authentication token
Response shape
[
{
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "Lower Third",
"ref": "lower-third",
"types": [
"lower-third"
],
"properties": {},
"config": {},
"labels": [
"Sport"
]
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/graphicpackages/{id}/graphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Rundowns
GET/api/v1/rundownsGet all rundowns
Retrieves a list of rundowns for the next 7 days, optionally filtered by date or persistent status. Returns only rundowns accessible to the authenticated user.
Query parameters
filter | object | optional | Optional filter criteria for date and persistent status |
Responses
- 200 Successfully retrieved rundowns matching the filter criteria
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/rundownsCreate a new rundown
Creates a new rundown with optional graphic package, match control, canvases, and outputs. Automatically creates a default playlist and hidden playlist for bundle/display hub graphics.
Request body
name | string | required | |
start | string | required | |
isPersistent | boolean | required | |
outputInstances | object | optional | |
sandboxInstances | object | optional | |
externalReference | string | required |
Responses
- 201 Rundown successfully created with associated playlists and configurations
- 400 Bad Request - Invalid input data or missing required fields
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"isPersistent": true,
"externalReference": "string"
}'POST/api/v1/rundowns/{id}/duplicateDuplicate a rundown
Deep-copies a rundown within the current workspace: playlists, playlist graphics, canvases, and match-control setup onto the same graphic package version. The copy is idle (no operator, not live, outputs configured but unclaimed, no external reference).
Path parameters
id | string | required | The unique UUID identifier of the rundown to duplicate |
Request body
name | string | optional | |
start | string | optional | |
isPersistent | boolean | optional |
Responses
- 201 Rundown successfully duplicated
- 400 Bad Request - Invalid input data
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
{
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/duplicate' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"start": "string",
"isPersistent": true
}'GET/api/v1/rundowns/liveGet all live rundowns
Returns a list of all rundowns that are currently live (actively being used for broadcast/output). Includes rundown ID, name, persistence status, and the timestamp when it went live.
Responses
- 200 Successfully retrieved all currently live rundowns
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/live' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}Get rundown by ID
Retrieves detailed information about a specific rundown including its relations (playlists, canvases, graphics). Also includes information about the creator and current operator.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Responses
- 200 Successfully retrieved the rundown with all relations
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
{
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/rundowns/{id}Update rundown
Updates an existing rundown with new data. Can modify name, start date, persistence status, graphic package, match control, canvases, and outputs. Automatically notifies connected clients of changes.
Path parameters
id | string | required | The unique UUID identifier of the rundown to update |
Request body
name | string | optional | |
start | string | optional | |
isPersistent | boolean | optional | |
outputInstances | object | optional | |
sandboxInstances | object | optional | |
externalReference | string | optional |
Responses
- 200 Rundown successfully updated with new data
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Rundown with the specified ID does not exist
- 409 Conflict - Rundown is locked and cannot be modified
Response shape
{
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z",
"unresolved": [
{}
]
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"isPersistent": true,
"outputInstances": {},
"sandboxInstances": {},
"externalReference": "string"
}'DELETE/api/v1/rundowns/{id}Delete rundown
Permanently deletes a rundown and all associated data (playlists, graphics assignments, match control). Cannot delete locked or live rundowns for safety reasons.
Path parameters
id | string | required | The unique UUID identifier of the rundown to delete |
Responses
- 200 Rundown successfully deleted
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Cannot delete live rundown or insufficient permissions
- 404 Not Found - Rundown with the specified ID does not exist
- 409 Conflict - Rundown is locked and cannot be deleted
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/playlistsGet playlists in rundown
Retrieves all playlists associated with a specific rundown, optionally filtered by playlist type (standard, hidden, etc.).
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Query parameters
filter | object | optional | Optional filter to retrieve specific playlist types |
Responses
- 200 Successfully retrieved all playlists in the rundown
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
[
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/playlists' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/playlistGraphicsGet playlist graphics in rundown
Retrieves all playlist graphics in the rundown, enriched with canvas information showing which canvases each graphic is assigned to. By default returns general and display hub types only, but can be filtered by any graphic type.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Query parameters
filter | object | optional | Optional filter to retrieve specific graphic types. If not provided, defaults to general and display hub types. |
Responses
- 200 Successfully retrieved all playlist graphics in the rundown with canvas assignments
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/playlistGraphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/matchControlGet match control configuration of rundown
Retrieves the match control configuration for a rundown. Match control manages live sports data such as scores, timers, periods, and team information. Returns null if no match control is configured.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Responses
- 200 Successfully retrieved match control configuration, or null if not configured
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
{
"id": "string",
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/matchControl' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/matchControl/graphicsGet match control playlist graphics
Retrieves all graphics in the match control playlist for a specific rundown. These are graphics automatically controlled by match events and data.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Responses
- 200 Successfully retrieved match control playlist graphics
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/matchControl/graphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/graphicsGet base graphics in rundown
Retrieves all general-type base graphics available in the rundown, optionally filtered to show only graphics assigned to canvases.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Query parameters
filter | object | optional | Optional filter to retrieve only graphics assigned to canvases |
Responses
- 200 Successfully retrieved base graphics in the rundown
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
[
{
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/graphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/quickGraphicsGet quick graphics in rundown
Retrieves all graphics marked as "quick graphics" in the rundown. Quick graphics are frequently used graphics that need rapid access during live production.
Path parameters
id | string | required | The unique UUID identifier of the rundown |
Responses
- 200 Successfully retrieved quick graphics in the rundown
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource does not exist
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/quickGraphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/rundowns/{id}/activeGraphics/{type}Get active graphics by output type
Retrieves all currently active general-type graphics in the rundown for a specific output type (sandbox, preview, or live).
Path parameters
id | string | required | The unique UUID identifier of the rundown |
type | "live" | "preview" | "sandbox" | required | The output type to filter active graphics |
Responses
- 200 Successfully retrieved active graphics for the specified output type
- 400 Bad Request - Invalid output type specified (must be sandbox, preview, or live)
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Rundown with the specified ID does not exist
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/rundowns/{id}/activeGraphics/{type}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Playlists
PATCH/api/v1/playlists/reorderReorder playlists within rundown
Updates the display order of playlists within their rundown. Changes the sequence in which playlists appear in the UI.
Request body
rundownId | string | required | |
playlists | string[] | required |
Responses
- 200 Successfully reordered playlists
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/reorder' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"rundownId": "string",
"playlists": [
"string"
]
}'POST/api/v1/playlistsCreate new playlist
Creates a new playlist within a rundown with specified name, order, and optional autoplay configuration.
Request body
name | string | required | |
rundownId | string | required |
Responses
- 201 Playlist successfully created
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"rundownId": "string"
}'GET/api/v1/playlists/{id}Get playlist by ID
Retrieves detailed information about a specific playlist including its graphics, display hubs, and autoplay configuration.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
Responses
- 200 Successfully retrieved the playlist
- 401 Unauthorized - Invalid or missing authentication token
- 404 Not Found - Resource does not exist
Response shape
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/playlists/{id}Update playlist
Updates playlist properties such as name, order, or autoplay configuration. Notifies connected clients of changes.
Path parameters
id | string | required | The unique UUID identifier of the playlist to update |
Request body
name | string | optional | |
rundownId | string | optional | |
autoplay | object | optional | Fields: isEnabled, isRunning, activeGraphicId, interval. |
Responses
- 200 Playlist successfully updated
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"rundownId": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
}
}'DELETE/api/v1/playlists/{id}Delete playlist
Permanently deletes a playlist and all its associated graphics and display hubs. Cannot delete playlist in locked rundown.
Path parameters
id | string | required |
Responses
- 200 Playlist successfully deleted
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Cannot delete playlist in locked rundown
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/playlists/{id}/duplicateDuplicate playlist
Creates a copy of an existing playlist including all its graphics and configurations. The duplicate is placed after the original.
Path parameters
id | string | required | The unique UUID identifier of the playlist to duplicate |
Responses
- 201 Playlist successfully duplicated
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"autoplay": {
"isEnabled": true,
"isRunning": true,
"activeGraphicId": {},
"interval": 1
},
"rundown": {
"id": "string",
"name": "string",
"start": "2026-01-01T18:00:00.000Z",
"editorId": {},
"createdBy": {},
"operatorId": {},
"usedBy": {},
"isPersistent": true,
"liveSince": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/duplicate' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/playlists/{id}/graphicsGet graphics in playlist
Retrieves all playlist graphics (with their data and configurations) for a specific playlist in display order.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
Responses
- 200 Successfully retrieved all graphics in the playlist
- 401 Unauthorized - Invalid or missing authentication token
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/playlists/{id}/graphicsAdd graphic to playlist
Adds a new graphic instance to the playlist with specified data, position, and output visibility settings.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
Request body
graphicId | string | required | |
name | string | optional | |
propertiesValues | object | optional |
Responses
- 201 Graphic successfully added to playlist
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"graphicId": "string"
}'PATCH/api/v1/playlists/{id}/graphics/reorderReorder graphics in playlist
Updates the display order of graphics within the playlist. Changes the sequence for playout and display.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
Request body
graphics | string[] | required |
Responses
- 200 Graphics successfully reordered
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
[
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}
]Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/reorder' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"graphics": [
"string"
]
}'GET/api/v1/playlists/{id}/graphics/{playlist_graphic_id}Get playlist graphic details
Retrieves detailed information about a specific graphic instance in the playlist including its data and current state.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
playlist_graphic_id | string | required | The unique UUID identifier of the playlist graphic |
Responses
- 200 Successfully retrieved the playlist graphic
- 401 Unauthorized - Invalid or missing authentication token
- 404 Not Found - Resource does not exist
Response shape
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/{playlist_graphic_id}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/playlists/{id}/graphics/{playlist_graphic_id}Update playlist graphic
Updates graphic data, output visibility, or other properties. Can update while graphic is live on air.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
playlist_graphic_id | string | required | The unique UUID identifier of the playlist graphic to update |
Request body
name | string | optional | |
propertiesValues | object | optional | |
isQuick | boolean | optional | |
updateLive | boolean | optional | |
updatePreview | boolean | optional | |
color | object | optional |
Responses
- 200 Playlist graphic successfully updated
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/{playlist_graphic_id}' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "string",
"propertiesValues": {},
"isQuick": true,
"updateLive": true,
"updatePreview": true,
"color": "oklch(0.75 0.1 240)"
}'DELETE/api/v1/playlists/{id}/graphics/{playlist_graphic_id}Delete playlist graphic
Removes a graphic from the playlist. If the graphic is currently on air, it will be taken off before deletion.
Path parameters
id | string | required | |
playlist_graphic_id | string | required |
Responses
- 200 Playlist graphic successfully deleted
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/{playlist_graphic_id}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/playlists/graphics/{playlist_graphic_id}/moveMove graphic to another playlist
Moves a playlist graphic from one playlist to another. The graphic will be appended to the end of the target playlist. The current playlist is determined from the graphic itself.
Path parameters
playlist_graphic_id | string | required | The unique UUID identifier of the playlist graphic to move |
Request body
playlistId | string | required | The UUID of the target playlist |
Responses
- 200 Playlist graphic successfully moved to target playlist
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/graphics/{playlist_graphic_id}/move' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"playlistId": "550e8400-e29b-41d4-a716-446655440000"
}'PATCH/api/v1/playlists/{id}/graphics/{playlist_graphic_id}/canvasesSet canvas output override
Overrides which canvases this specific playlist graphic instance outputs to.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
playlist_graphic_id | string | required | The unique UUID identifier of the playlist graphic |
Request body
canvasIds | string[] | required |
Responses
- 200 Canvas override successfully updated
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"canvasOverride": [
"string"
]
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/{playlist_graphic_id}/canvases' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"canvasIds": [
"string"
]
}'POST/api/v1/playlists/{id}/graphics/{playlist_graphic_id}/duplicateDuplicate playlist graphic
Creates a copy of an existing playlist graphic including all its data. The duplicate is placed after the original.
Path parameters
id | string | required | The unique UUID identifier of the playlist |
playlist_graphic_id | string | required | The unique UUID identifier of the playlist graphic to duplicate |
Responses
- 201 Playlist graphic successfully duplicated
- 401 Unauthorized - Invalid or missing authentication token
- 403 Forbidden - Insufficient permissions
Response shape
{
"id": "string",
"name": "string",
"playlist": null,
"graphic": {
"id": "string",
"ref": "string",
"graphicPackage": {
"id": "string",
"ref": "string",
"name": "string",
"version": "string",
"deprecated": true,
"description": "string",
"cdnUrl": "string",
"controls": [],
"config": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"parentId": {},
"types": [],
"name": "string",
"description": "string",
"thumbnail": {},
"properties": {},
"config": {},
"labels": [],
"states": {},
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
},
"status": {},
"state": {},
"isQuick": true,
"isConcept": true,
"propertiesValues": {},
"order": 1,
"createdAt": "2026-01-01T18:00:00.000Z",
"updatedAt": "2026-01-01T18:00:00.000Z"
}Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/playlists/{id}/graphics/{playlist_graphic_id}/duplicate' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Audit
GET/api/v1/audit/logsList audit logs
Returns audit entries filtered by entity, action, or user information.
Query parameters
page | integer | optional | Page number (1-indexed). |
limit | integer | optional | Max number of entries to return per page. |
filter | object | optional |
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/audit/logs' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'MosIntegrator
GET/api/v1/mos/rundown/{mosId}
Path parameters
mosId | string | required |
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/rundown/{mosId}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/mos/rundown
Responses
- 201 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/rundown' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/mos/rundown
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/rundown' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'DELETE/api/v1/mos/rundown/{mosId}/{roId}
Path parameters
mosId | string | required | |
roId | string | required |
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/rundown/{mosId}/{roId}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/mos/rundown/sync
Responses
- 201 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/rundown/sync' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/api/v1/mos/status
Query parameters
mosId | string | required |
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/status?mosId=' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/mos/auto-fetch
Responses
- 200 OK
Example
curl 'https://graphics-api.use2.mxmz.io/api/v1/mos/auto-fetch' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Package Manager
Graphics packages and their published releases. An integration that puts graphics on air needs the released package endpoints to find the release to load.
Base URL https://package-manager-api.use2.mxmz.io OpenAPI document
Health
GET/healthHealth check endpoint
Returns the health status of the Graphics Package Manager
Responses
- 200 Service is healthy
Response shape
{
"status": "healthy",
"timestamp": "2026-01-01T18:00:00.000Z",
"service": "graphics-package-manager-service",
"version": "1.0.0"
}Example
curl 'https://package-manager-api.use2.mxmz.io/health' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/Service information
Returns basic information about the data Graphics Package Manager
Responses
- 200 Service information
Response shape
{
"name": "MXMZ Graphics Package Manager",
"version": "1.0.0",
"description": "Manager for MXMZ Graphics Packages"
}Example
curl 'https://package-manager-api.use2.mxmz.io/' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Tenant
GET/tenant/database-connection-testValidate tenant database connectivity
Checks whether the tenant-aware database can be reached using the workspace header.
Responses
- 200 Database connection succeeded
Response shape
{
"success": true,
"database": "tenant-db"
}Example
curl 'https://package-manager-api.use2.mxmz.io/tenant/database-connection-test' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Graphic Package
GET/packages/workspace
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/workspace' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/packages/{id}/source
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/source' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/packages/{id}/builds
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/builds' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/packages/{id}/releases
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/releases' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/packages/{id}/release
Path parameters
id | string | required |
Request body
An empty JSON object.
Responses
- 201 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/release' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{}'GET/packages/{id}/drafts
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/drafts' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/packages/{id}/draft
Path parameters
id | string | required |
Request body
An empty JSON object.
Responses
- 201 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/draft' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{}'GET/packages/{id}/versions
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}/versions' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'DELETE/packages/{id}
Path parameters
id | string | required |
Responses
- 200 OK
Example
curl 'https://package-manager-api.use2.mxmz.io/packages/{id}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Graphic Package Public
GET/public/packages/{hash}/versionsList all versions for a graphic package
Decodes the hashed identifier and returns the package metadata along with every published version sorted chronologically.
Path parameters
hash | string | required |
Responses
- 200 Package metadata with an array of available versions.
- 404 Returned when the hash cannot be resolved or no versions exist.
Response shape
{
"id": "pkg_123",
"name": "Broadcast Bug Package",
"description": "Reusable broadcast graphics.",
"versions": [
{
"version": "1.4.0",
"cdnUrl": "https://cdn.example.com/graphics/pkg_123/v1.4.0"
}
]
}Example
curl 'https://package-manager-api.use2.mxmz.io/public/packages/{hash}/versions' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Released Graphic Package
GET/released/packagesGet all released graphic packages (latest version per major per package)
Responses
- 200 List of packages with latest release per major version.
Example
curl 'https://package-manager-api.use2.mxmz.io/released/packages' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'GET/released/packages/{id}/{version}Get a released graphic package version
Returns the latest release for the requested major version, or the latest release for the package when version is "latest".
Path parameters
id | string | required | Graphic package UUID |
version | string | required | Major version number or "latest" |
Responses
- 200 The selected released package version.
- 404 Returned when the package or selected major version does not exist.
Example
curl 'https://package-manager-api.use2.mxmz.io/released/packages/{id}/{version}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Playout Service
Outputs, and the service that puts graphics on air. The REST surface manages outputs. Control happens over the websocket described further down.
Base URL https://playout-service.use2.mxmz.io OpenAPI document
App
GET/healthz
Responses
- 200 OK
Example
curl 'https://playout-service.use2.mxmz.io/healthz' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Outputs
GET/api/v1/outputsList outputs
Query parameters
page | number | optional | Page number to return. |
limit | number | optional | Number of items to return per page. Maximum 100. |
Responses
- 200 OK
Response shape
{
"meta": {
"page": 1,
"limit": 20,
"totalItems": 42,
"totalPages": 3,
"hasNextPage": true,
"hasPreviousPage": false
},
"data": [
{
"uuid": "019ad2f1-2f3b-7c2e-9a8f-3f4b7b9c0d11",
"name": "Main output",
"channel": "N2MwYzQxNmQtNGEzMS0xMWYxLThlOWEtMWFiYWI2ODU5YWM3Ojo6MDE5ZTAzNDMtMWFlOS03MWM1LTgwMmQtYTRmY2IzYjJhYjky"
}
]
}Example
curl 'https://playout-service.use2.mxmz.io/api/v1/outputs' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'POST/api/v1/outputsCreate an output
Request body
name | string | required | Human-readable output name. |
Responses
- 201 OK
Response shape
{
"uuid": "019ad2f1-2f3b-7c2e-9a8f-3f4b7b9c0d11",
"name": "Main output",
"channel": "N2MwYzQxNmQtNGEzMS0xMWYxLThlOWEtMWFiYWI2ODU5YWM3Ojo6MDE5ZTAzNDMtMWFlOS03MWM1LTgwMmQtYTRmY2IzYjJhYjky"
}Example
curl 'https://playout-service.use2.mxmz.io/api/v1/outputs' \
--request POST \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Main output"
}'GET/api/v1/outputs/{uuid}Get an output by UUID
Path parameters
uuid | string | required |
Responses
- 200 OK
- 404 Output not found.
Response shape
{
"uuid": "019ad2f1-2f3b-7c2e-9a8f-3f4b7b9c0d11",
"name": "Main output",
"channel": "N2MwYzQxNmQtNGEzMS0xMWYxLThlOWEtMWFiYWI2ODU5YWM3Ojo6MDE5ZTAzNDMtMWFlOS03MWM1LTgwMmQtYTRmY2IzYjJhYjky"
}Example
curl 'https://playout-service.use2.mxmz.io/api/v1/outputs/{uuid}' \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'PATCH/api/v1/outputs/{uuid}Update an output
Path parameters
uuid | string | required |
Request body
name | string | optional | Human-readable output name. |
Responses
- 200 OK
- 404 Output not found.
Response shape
{
"uuid": "019ad2f1-2f3b-7c2e-9a8f-3f4b7b9c0d11",
"name": "Main output",
"channel": "N2MwYzQxNmQtNGEzMS0xMWYxLThlOWEtMWFiYWI2ODU5YWM3Ojo6MDE5ZTAzNDMtMWFlOS03MWM1LTgwMmQtYTRmY2IzYjJhYjky"
}Example
curl 'https://playout-service.use2.mxmz.io/api/v1/outputs/{uuid}' \
--request PATCH \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"name": "Backup output"
}'DELETE/api/v1/outputs/{uuid}Delete an output
Path parameters
uuid | string | required |
Responses
- 204 Output deleted.
- 404 Output not found.
Example
curl 'https://playout-service.use2.mxmz.io/api/v1/outputs/{uuid}' \
--request DELETE \
--header 'x-mxmz-client-id: YOUR_CLIENT_ID' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'Playout websocket messages
The Playout Service uses Socket.IO over the websocket transport. Controllers send commands, the service forwards them to the players that render the output.
| Namespace | Who connects | What it does |
|---|---|---|
/control | Controller clients | Claims an output and sends commands. This is what an integration implements. |
/player | Player clients | Subscribes to an output and receives commands. Used by the MXMZ renderer and player pages. |
Connect and authenticate
A control client must resolve to a current user with a workspace and one of the playout, admin or superadmin roles before it can claim a session. The service reads credentials from the Socket.IO handshake auth first, then from headers or cookies.
{
auth: {
accessToken?: string; // or the configured access token cookie
bearerTokenId?: string; // or the configured client id header
authorization?: string; // or the Authorization header
}
}With an API key, pass the Client ID as bearerTokenId and the Secret as authorization:
import { io } from "socket.io-client";
const socket = io("https://playout-service.use2.mxmz.io/control", {
transports: ["websocket"],
auth: {
bearerTokenId: CLIENT_ID,
authorization: "Bearer " + SECRET_TOKEN,
},
});
socket.on("error", ({ code, message }) => console.error(code, message));
// 1. Claim the output. outputUuid must be a UUID v7.
socket.emit("request_session", { outputUuid: OUTPUT_UUID, force: false });
socket.on("session_started", () => {
// 2. Keep the session alive. The TTL is 60 seconds.
setInterval(() => socket.emit("heartbeat"), 25000);
// 3. Load a released package on the live channel.
socket.emit("setGraphicsPackage", { outputType: "live", payload: { url: CDN_URL } });
// 4. Animate a graphic in, with data.
socket.emit("animateTo", {
outputType: "live",
payload: { graphicUuid: GRAPHIC_UUID, timelineLabel: "in", data: { name: "Jane Doe" } },
});
});CDN_URL is the cdnUrl returned by the released package endpoint of the Package Manager. Graphic and datafield identifiers come from that release JSON.
Shared payloads
Error
Emitted as the error event in both namespaces.
{
code: string;
message: string;
}| Code | What it points at |
|---|---|
unauthorized | Credentials are missing, wrong, or from the other region. |
workspace_required | The account authenticated but has no workspace. |
forbidden | The account lacks the playout, admin or superadmin role. |
invalid_output | The output UUID is malformed. It must be a UUID v7. |
output_not_found | No such output in this workspace or region. |
output_claimed | Another controller holds the session. Retry with force: true to take over. |
session_required | A command was sent before request_session succeeded. |
heartbeat_failed | The session lapsed because the 60 second TTL expired. |
invalid_channel | The outputType is not live, preview or sandbox. |
Control session payload
{
sessionId: string;
workspaceId: string;
outputUuid: string;
}Controller command envelope
All controller command messages use this envelope. The gateway validates outputType and forwards the command only when a control session exists. payload is specific to the command and optional at transport level.
{
outputType: 'live' | 'preview' | 'sandbox';
payload?: unknown;
}Player command payload
Controller commands are forwarded to subscribed players using the target outputType as the Socket.IO event name. A controller message with outputType: 'live' reaches players as a live event:
{
event: string;
payload?: unknown;
}The /control namespace
Client to service
| Event | Payload | Notes |
|---|---|---|
request_session | { outputUuid: string; force?: boolean } | Claims the output for this controller. outputUuid must be UUID v7. force: true revokes the current owner if another active session exists. |
release_session | none | Releases the current control session. |
heartbeat | none | Refreshes the session TTL. Control session TTL is 60 seconds. |
request_state | none | Requests the persisted state snapshots for the claimed output. |
setGraphicsPackage | Command envelope | Forwards to players and stores the current graphics package. |
setDlsBackground | Command envelope | Forwards to players and stores or clears the current DLS background. |
graphicsPackage | Command envelope | Forwards to players. Does not update persisted replay state. |
animateTo | Command envelope | Forwards to players and updates active graphic playback state. |
seekTo | Command envelope | Forwards to players and updates active graphic playback state. |
seekPosition | Command envelope | Forwards to players. Does not update persisted replay state. |
play | Command envelope | Forwards to players. Does not update persisted replay state. |
pause | Command envelope | Forwards to players. Does not update persisted replay state. |
setData | Command envelope | Forwards to players and updates active graphic data. |
reload | Command envelope | Forwards to players. Does not update persisted replay state. |
clear | Command envelope | Clears persisted state for the outputType and forwards to players as event: 'reload'. |
Commands that persist state are replayed to a player that reconnects. Anything sent with a command that does not persist is gone after a renderer restart.
Common command payloads
| Event | Payload | Effect |
|---|---|---|
setGraphicsPackage | { url: cdnUrl } | Loads a released package on the channel. A channel with no package ignores every other command. |
animateTo | { graphicUuid, timelineLabel, data?, swapActiveGraphic? } | Plays to a labelled timeline point, usually in or out. |
setData | { graphicUuid, data } | Updates datafields in place without replaying the animation. |
clear | {} | Empties the channel. |
Service to client
| Event | Payload | Notes |
|---|---|---|
session_started | Control session payload | Emitted after a successful request_session. |
session_ended | Control session payload | Emitted after a successful release_session. |
heartbeat | Control session payload | Emitted after a successful heartbeat refresh. |
state | State payload | Emitted after request_state. |
session_revoked | Control session payload plus { revokedBySessionId: string } | Emitted to the previous controller when another controller claims the same output by force. |
error | Error payload | Emitted for validation, auth, session or output errors. |
State payload
The answer to request_state. It reflects what the service was told through persisting commands, which makes it the right call after a reconnect. It is not a readback of what a renderer is drawing.
{
sessionId: string;
workspaceId: string;
outputUuid: string;
states: Array<{
outputType: string;
state: {
currentGraphicsPackage?: {
payload: unknown;
};
backgroundVideo?: {
payload: unknown;
};
activeGraphics: Array<{
id: string;
graphicUuid: string;
data?: unknown;
playbackPayload?: unknown;
}>;
};
}>;
}