Actions API

Fire widget actions and send test alerts that show on stream.

View as Markdown

On this page

Authenticate with a personal token as Authorization: Bearer pxp_...; the operations are also MCP tools unless noted. The full machine-readable definition is in the OpenAPI specification.

Operation	Method and path	Scope
Fire widget command	`POST /overlays/{overlayId}/members/{memberId}/commands`	`actions:fire`
Send test alert	`POST /overlays/{overlayId}/members/{memberId}/test-alert`	`actions:fire`
List deck buttons	`GET /overlays/{overlayId}/deck-macros`	`overlays:read`
Run deck button	`POST /overlays/{overlayId}/deck-macros/{macroId}/fire`	`actions:fire`
Replay alert	`POST /overlays/{overlayId}/members/{memberId}/replay`	`actions:fire`
List media favorites	`GET /overlays/{overlayId}/media/favorites`	`overlays:read`
Show media on air	`POST /overlays/{overlayId}/members/{memberId}/media/show`	`actions:fire`
Hide media	`POST /overlays/{overlayId}/members/{memberId}/media/hide`	`actions:fire`

Operations

POST/api/v1/overlays/{overlayId}/members/{memberId}/commands

ON AIR: fires one of the layer's declared chat commands (see get_overlay commands), exactly as if it was typed in chat by the broadcaster. Undeclared commands are rejected.

Scope: actions:fire (Trigger widgets on air) · MCP tool: fire_member_command · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	Layer (member) id (from get_overlay or list_members). At least 1
`cmd`	body	string	required	Full command text, e.g. "!goaladd 5". Up to 500 characters

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/commands" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cmd": "..." }'

JavaScript

const overlayId = '<overlayId>';
const memberId = '<memberId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/commands`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ cmd: "..." }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Send test alert

POST/api/v1/overlays/{overlayId}/members/{memberId}/test-alert

ON AIR: sends a fake stream event (follow, sub, cheer, raid, donation ...) to this one layer, e.g. to preview an alert box. Only this layer sees it; it does not trigger automations or bot actions.

Scope: actions:fire (Trigger widgets on air) · MCP tool: send_test_alert · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	Layer (member) id (from get_overlay or list_members). At least 1
`type`	body	`follow`, `sub`, `subgift`, `resub`, `cheer`, `raid`, `donation`, `membership`, `commission`, `merch`	required

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/test-alert" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "follow" }'

JavaScript

const overlayId = '<overlayId>';
const memberId = '<memberId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/test-alert`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: "follow" }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

List deck buttons

GET/api/v1/overlays/{overlayId}/deck-macros

Lists the custom deck buttons (macros) of an overlay with their steps (scene switch, widget command, media favorite, position, layout, video, delay) and the studio rights they need.

Scope: overlays:read (Read overlays) · MCP tool: list_deck_macros · Notes: read only

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`includeStyle`	query	boolean	optional	Also return each button's color and icon

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/deck-macros" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/deck-macros`, {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Run deck button

POST/api/v1/overlays/{overlayId}/deck-macros/{macroId}/fire

ON AIR: runs one deck button (macro) like pressing it on the deck: every step in order (scene switches, widget commands, media, layout changes). Each step reports its own result; a failed step does not stop the rest.

Scope: actions:fire (Trigger widgets on air) · MCP tool: fire_deck_macro · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`macroId`	path	integer	required	Deck button id (from list_deck_macros). At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/deck-macros/<macroId>/fire" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';
const macroId = '<macroId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/deck-macros/${macroId}/fire`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Replay alert

POST/api/v1/overlays/{overlayId}/members/{memberId}/replay

ON AIR: plays a past stream event (eventId from list_activity) again on one alert box layer, e.g. to show a raid alert a second time. Only alert box layers can replay; it does not count as a new event.

Scope: actions:fire (Trigger widgets on air) · MCP tool: replay_activity_event · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	Layer (member) id (from get_overlay or list_members). At least 1
`eventId`	body	integer	required	Event id from list_activity. At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/replay" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "eventId": 1 }'

JavaScript

const overlayId = '<overlayId>';
const memberId = '<memberId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/replay`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ eventId: 1 }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

List media favorites

GET/api/v1/overlays/{overlayId}/media/favorites

Lists the saved media favorites (GIFs, stickers, clips) of an overlay that show_media can put on air.

Scope: overlays:read (Read overlays) · MCP tool: list_media_favorites · Notes: read only

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/media/favorites" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/media/favorites`, {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Show media on air

POST/api/v1/overlays/{overlayId}/members/{memberId}/media/show

ON AIR: shows a saved media favorite (favoriteId from list_media_favorites) on the overlay's media layer right away. Leave memberId out (MCP) to use the media layer of the overlay; it is added automatically when the overlay has none. Only saved favorites, no free links.

Scope: actions:fire (Trigger widgets on air) · MCP tool: show_media · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	optional	Media layer id. Optional outside the REST path: without it the overlay's media layer is used or added. At least 1
`favoriteId`	body	integer	required	Favorite id from list_media_favorites. At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/media/show" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "favoriteId": 1 }'

JavaScript

const overlayId = '<overlayId>';
const memberId = '<memberId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/media/show`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ favoriteId: 1 }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Hide media

POST/api/v1/overlays/{overlayId}/members/{memberId}/media/hide

Hides everything currently shown on the media layer (all GIFs and clips). Nothing new appears on air. memberId may be left out (MCP) to use the overlay's media layer.

Scope: actions:fire (Trigger widgets on air) · MCP tool: hide_media

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	optional	Media layer id. Optional outside the REST path. At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/media/hide" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const overlayId = '<overlayId>';
const memberId = '<memberId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/media/hide`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Was this page helpful?

Actions API

Operations

Fire widget command

Send test alert

List deck buttons

Run deck button

Replay alert

List media favorites

Show media on air

Hide media