# Actions API

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

Authenticate with a [personal token](/docs/api#personal-tokens) as `Authorization: Bearer pxp_...`; the operations are also [MCP tools](/docs/connect-ai) unless noted. The full machine-readable definition is in the [OpenAPI specification](https://pxstudio.cloud/api/v1/openapi.json).

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

## Operations

### Fire widget command

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
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
```js
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

```http Endpoint
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 |  |

::: tabs
@@ cURL
```bash
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
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/deck-macros" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/deck-macros/<macroId>/fire" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
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
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/media/favorites" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
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
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
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
```js
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();
```
:::