Automations API

Automation rules: when something happens, do something.

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
List automations	`GET /automations`	`automations:read`
Get automation options	`GET /automations/options`	`automations:read`
List automation activity	`GET /automations/activity`	`automations:read`
Create automation	`POST /automations`	`automations:write`
Update automation	`PATCH /automations/{ruleId}`	`automations:write`
Switch automation on or off	`PUT /automations/{ruleId}/enabled`	`automations:write`
Delete automation	`DELETE /automations/{ruleId}`	`automations:write`
List action webhooks	`GET /automations/webhooks`	`automations:read`
Delete action webhook	`DELETE /automations/webhooks/{webhookId}`	`automations:write`

Operations

List automations

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

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/automations" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/automations/options" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/automations/activity" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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)

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/automations" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "trigger": {}, "action": {} }'

JavaScript

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

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)

Terminal

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

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

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

Terminal

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

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

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

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/automations/<ruleId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/automations/webhooks" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/automations/webhooks/<webhookId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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();

Was this page helpful?