# Automations API

Automation rules: when something happens, do something.

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 |
| --- | --- | --- |
| [List automations](#list-automations) | `GET /automations` | `automations:read` |
| [Get automation options](#get-automation-options) | `GET /automations/options` | `automations:read` |
| [List automation activity](#list-automation-activity) | `GET /automations/activity` | `automations:read` |
| [Create automation](#create-automation) | `POST /automations` | `automations:write` |
| [Update automation](#update-automation) | `PATCH /automations/{ruleId}` | `automations:write` |
| [Switch automation on or off](#switch-automation-on-or-off) | `PUT /automations/{ruleId}/enabled` | `automations:write` |
| [Delete automation](#delete-automation) | `DELETE /automations/{ruleId}` | `automations:write` |
| [List action webhooks](#list-action-webhooks) | `GET /automations/webhooks` | `automations:read` |
| [Delete action webhook](#delete-action-webhook) | `DELETE /automations/webhooks/{webhookId}` | `automations:write` |

## Operations

### List automations

```http Endpoint
GET /api/v1/automations
```

Lists your automation rules ("when X happens, do Y"): trigger, conditions, the action with readable targets (overlay and layer) and whether each rule is on.

**Scope:** `automations:read` (Read automations) · **MCP tool:** `list_automations` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/automations" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/automations', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Get automation options

```http Endpoint
GET /api/v1/automations/options
```

Returns what an automation rule can use: trigger types, action types, the scene condition and your overlays with scenes, spots, groups and layers (as overlayId and memberId, with the widget commands each layer declares).

**Scope:** `automations:read` (Read automations) · **MCP tool:** `get_automation_options` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/automations/options" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/automations/options', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### List automation activity

```http Endpoint
GET /api/v1/automations/activity
```

Lists the latest automation runs (rule name, action type, time), newest first.

**Scope:** `automations:read` (Read automations) · **MCP tool:** `list_automation_activity` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/automations/activity" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/automations/activity', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Create automation

```http Endpoint
POST /api/v1/automations
```

ON AIR: creates an automation rule that from now on runs by itself whenever its trigger happens (show alerts, switch scenes, post in chat, change the stream title). Targets are layers as overlayId and memberId. New Discord rules cannot be created through the API (the webhook URL is a secret).

**Scope:** `automations:write` (Change automations) · **MCP tool:** `create_automation` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | body | string | required | Up to 60 characters |
| `enabled` | body | boolean | optional | False saves the rule switched off |
| `cooldownSec` | body | integer | optional | Seconds before the rule can fire again (0 = no cooldown). 0 to 86400 |
| `trigger` | body | object | required | When the rule fires. type: follow, sub, subgift, resub, cheer, raid, donation, mod-action (a mod types a command), chat-command (a PXStudioBot command), bot-timer. minAmount: only from this amount (bits, gifted subs, months, tier 1-3, raid viewers, donation amount). command: only for this chat command (chat-command). modCommand: only for this mod command (mod-action) |
| `onlyWhenSceneLive` | body | integer or null | optional | Optional condition: the rule only fires while this scene is live (sceneId from get_automation_options). null removes the condition. At least 1 |
| `action` | body | object | required | What the rule does. Fields per type: widget-command {overlayId, memberId, cmd, presetName?} fires a widget command on a layer; scene-golive {overlayId, sceneId} puts a scene on air; set-title {title} and set-category {category} change your Twitch stream; member-to-spot {overlayId, spotId, memberId or groupId} moves a layer to a saved spot; bot-say {text, platforms?} posts in your chat; media-show {overlayId, favoriteId} shows a media favorite; discord-webhook {template} only for an existing Discord rule (its webhook URL is a secret and stays as it is; new Discord rules cannot be set up through the API) |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/automations" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "trigger": {}, "action": {} }'
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/automations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: "...", trigger: {}, action: {} }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Update automation

```http Endpoint
PATCH /api/v1/automations/{ruleId}
```

ON AIR: changes an automation rule (send only what changes; the rest stays). The changed rule runs by itself from now on. A Discord rule keeps its webhook URL; only its message template can change here.

**Scope:** `automations:write` (Change automations) · **MCP tool:** `update_automation` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ruleId` | path | integer | required | Automation rule id (from list_automations). At least 1 |
| `name` | body | string | optional | Up to 60 characters |
| `enabled` | body | boolean | optional | False saves the rule switched off |
| `cooldownSec` | body | integer | optional | Seconds before the rule can fire again (0 = no cooldown). 0 to 86400 |
| `trigger` | body | object | optional | When the rule fires. type: follow, sub, subgift, resub, cheer, raid, donation, mod-action (a mod types a command), chat-command (a PXStudioBot command), bot-timer. minAmount: only from this amount (bits, gifted subs, months, tier 1-3, raid viewers, donation amount). command: only for this chat command (chat-command). modCommand: only for this mod command (mod-action) |
| `onlyWhenSceneLive` | body | integer or null | optional | Optional condition: the rule only fires while this scene is live (sceneId from get_automation_options). null removes the condition. At least 1 |
| `action` | body | object | optional | What the rule does. Fields per type: widget-command {overlayId, memberId, cmd, presetName?} fires a widget command on a layer; scene-golive {overlayId, sceneId} puts a scene on air; set-title {title} and set-category {category} change your Twitch stream; member-to-spot {overlayId, spotId, memberId or groupId} moves a layer to a saved spot; bot-say {text, platforms?} posts in your chat; media-show {overlayId, favoriteId} shows a media favorite; discord-webhook {template} only for an existing Discord rule (its webhook URL is a secret and stays as it is; new Discord rules cannot be set up through the API) |

::: tabs
@@ cURL
```bash
curl -X PATCH "https://pxstudio.cloud/api/v1/automations/<ruleId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "enabled": true }'
```
@@ JavaScript
```js
const ruleId = '<ruleId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/automations/${ruleId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: "...", enabled: true }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Switch automation on or off

```http Endpoint
PUT /api/v1/automations/{ruleId}/enabled
```

ON AIR: switches an automation rule on (it runs by itself from now on) or off.

**Scope:** `automations:write` (Change automations) · **MCP tool:** `set_automation_enabled` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ruleId` | path | integer | required | Automation rule id (from list_automations). At least 1 |
| `enabled` | body | boolean | required |  |

::: tabs
@@ cURL
```bash
curl -X PUT "https://pxstudio.cloud/api/v1/automations/<ruleId>/enabled" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```
@@ JavaScript
```js
const ruleId = '<ruleId>';

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

### Delete automation

```http Endpoint
DELETE /api/v1/automations/{ruleId}
```

DESTRUCTIVE: deletes an automation rule. Cannot be undone.

**Scope:** `automations:write` (Change automations) · **MCP tool:** `delete_automation` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ruleId` | path | integer | required | Automation rule id (from list_automations). At least 1 |

::: tabs
@@ cURL
```bash
curl -X DELETE "https://pxstudio.cloud/api/v1/automations/<ruleId>" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const ruleId = '<ruleId>';

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

### List action webhooks

```http Endpoint
GET /api/v1/automations/webhooks
```

Lists your action webhooks (name, action type, created and last used). The webhook links themselves are never shown.

**Scope:** `automations:read` (Read automations) · **MCP tool:** `list_action_webhooks` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/automations/webhooks" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/automations/webhooks', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Delete action webhook

```http Endpoint
DELETE /api/v1/automations/webhooks/{webhookId}
```

DESTRUCTIVE: deletes an action webhook. Stream Deck buttons or scripts that call its link stop working. Cannot be undone.

**Scope:** `automations:write` (Change automations) · **MCP tool:** `delete_action_webhook` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | integer | required | Webhook id (from list_action_webhooks). At least 1 |

::: tabs
@@ cURL
```bash
curl -X DELETE "https://pxstudio.cloud/api/v1/automations/webhooks/<webhookId>" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const webhookId = '<webhookId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/automations/webhooks/${webhookId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::