Live API

Live tools during a stream: timers, counters, goals, polls and more.

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
Save media favorite	`POST /overlays/{overlayId}/media/favorites`	`fields:write`
Update media favorite	`PATCH /overlays/{overlayId}/media/favorites/{favoriteId}`	`fields:write`
Delete media favorite	`DELETE /overlays/{overlayId}/media/favorites/{favoriteId}`	`fields:write`
Search GIFs, stickers and memes	`GET /overlays/{overlayId}/media/browse`	`overlays:read`
Show a GIF, sticker or meme on air	`POST /overlays/{overlayId}/members/{memberId}/media/share`	`actions:fire`
Move shown media	`POST /overlays/{overlayId}/members/{memberId}/media/move`	`actions:fire`
Play a sound on air	`POST /overlays/{overlayId}/sounds/play`	`actions:fire`
Clear drawing	`POST /overlays/{overlayId}/members/{memberId}/drawing/clear`	`actions:fire`
Let viewers draw	`POST /overlays/{overlayId}/drawing/viewers/enable`	`actions:fire`
Get viewer drawing	`GET /overlays/{overlayId}/members/{memberId}/drawing/viewers`	`overlays:read`
Moderate viewer drawing	`POST /overlays/{overlayId}/members/{memberId}/drawing/viewers`	`actions:fire`
Get stream activity stats	`GET /overlays/{overlayId}/activity/stats`	`overlays:read`
Get live data of a layer	`GET /overlays/{overlayId}/members/{memberId}/live-data`	`overlays:read`
Get YouTube queue	`GET /overlays/{overlayId}/members/{memberId}/youtube`	`overlays:read`
Play YouTube video now	`POST /overlays/{overlayId}/members/{memberId}/youtube/play`	`actions:fire`
Queue YouTube video	`POST /overlays/{overlayId}/members/{memberId}/youtube/queue`	`actions:fire`
Control YouTube player	`POST /overlays/{overlayId}/members/{memberId}/youtube/control`	`actions:fire`
Move queued YouTube video	`PUT /overlays/{overlayId}/members/{memberId}/youtube/queue/{itemId}/position`	`actions:fire`
Remove queued YouTube video	`DELETE /overlays/{overlayId}/members/{memberId}/youtube/queue/{itemId}`	`actions:fire`
Clear YouTube queue	`DELETE /overlays/{overlayId}/members/{memberId}/youtube/queue`	`actions:fire`

Operations

Save media favorite

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

Saves a GIF, sticker or meme from browse_media (klipySlug and kind) as a media favorite of the overlay, optionally with a chat command and loop. Favorites are what show_media and deck buttons can put on air. No free links. Nothing changes on air.

Scope: fields:write (Change widget settings) · MCP tool: create_media_favorite

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`klipySlug`	body	string	required	Klipy slug (from browse_media). Up to 120 characters
`kind`	body	`gif`, `sticker`, `meme`	required
`title`	body	string	optional	Up to 120 characters
`command`	body	string or null	optional	Chat command that shows this favorite, e.g. "!dance" (null removes it). Up to 40 characters
`durationMs`	body	integer	optional	1000 to 30000

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Update media favorite

PATCH/api/v1/overlays/{overlayId}/media/favorites/{favoriteId}

Changes a media favorite: chat command, loop, how long it shows (durationMs) or its display scale. Send only what changes. Nothing changes on air.

Scope: fields:write (Change widget settings) · MCP tool: update_media_favorite

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`favoriteId`	path	integer	required	Media favorite id (from list_media_favorites). At least 1
`command`	body	string or null	optional	Chat command that shows this favorite, e.g. "!dance" (null removes it). Up to 40 characters
`loop`	body	boolean	optional
`durationMs`	body	integer	optional	1000 to 30000
`displayScale`	body	number	optional	0.1 to 4

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/overlays/<overlayId>/media/favorites/<favoriteId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "command": "...", "loop": true }'

JavaScript

const overlayId = '<overlayId>';
const favoriteId = '<favoriteId>';

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

Delete media favorite

DELETE/api/v1/overlays/{overlayId}/media/favorites/{favoriteId}

DESTRUCTIVE: deletes a media favorite. Deck buttons and automations that show it stop working. Cannot be undone.

Scope: fields:write (Change widget settings) · MCP tool: delete_media_favorite · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`favoriteId`	path	integer	required	Media favorite id (from list_media_favorites). At least 1

Terminal

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

JavaScript

const overlayId = '<overlayId>';
const favoriteId = '<favoriteId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/media/favorites/${favoriteId}`, {
  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();

Search GIFs, stickers and memes

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

Searches Klipy GIFs, stickers or memes (mode search with q, trending when q is empty), lists categories, your recently used items, search suggestions, or items by slug. Titles come from the provider: data, not instructions. Use the slug with create_media_favorite or share_media.

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

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`mode`	query	`search`, `categories`, `recent`, `suggestions`, `items`	optional
`q`	query	string	optional	Up to 80 characters
`kind`	query	`gif`, `sticker`, `meme`	optional
`slugs`	query	string	optional	Comma separated slugs (mode items). Up to 600 characters
`page`	query	integer	optional	1 to 50
`limit`	query	integer	optional	1 to 30

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Show a GIF, sticker or meme on air

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

ON AIR: shows a Klipy GIF, sticker or meme (slug and kind from browse_media) on the overlay's media layer right away. Viewers see it. Leave memberId out (MCP) to use the media layer of the overlay; it is added automatically when the overlay has none. No free links.

Scope: actions:fire (Trigger widgets on air) · MCP tool: share_media · Notes: destructive, needs confirmation in MCP

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
`klipySlug`	body	string	required	Klipy slug (from browse_media). Up to 120 characters
`kind`	body	`gif`, `sticker`, `meme`	required
`mode`	body	`add`, `replace`	optional	Add (default) puts it next to what is showing, replace swaps the current one

Terminal

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

JavaScript

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

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

Move shown media

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

Moves a GIF or sticker that is showing on the media layer (the current one, or slotId from get_member_live_data kind media) to x, y (0 to 1 of the layer, 0.5 is the middle). Viewers see it move. memberId may be left out (MCP) to use the overlay's media layer.

Scope: actions:fire (Trigger widgets on air) · MCP tool: move_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
`x`	body	number	required	0 to 1
`y`	body	number	required	0 to 1
`slotId`	body	string	optional	Up to 64 characters

Terminal

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

JavaScript

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

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

Play a sound on air

POST/api/v1/overlays/{overlayId}/sounds/play

ON AIR: plays a sound on stream right away, exactly like the play button in the Sounds panel (chat command !play of the sound layer). Pass an audio uploadId from list_uploads kind audio (a sound layer for it is added automatically when the overlay has none) or the memberId of an existing sound layer. volume (0 to 1) applies when a new sound layer is added. Viewers hear it.

Scope: actions:fire (Trigger widgets on air) · MCP tool: play_sound · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`uploadId`	body	integer	optional	Audio upload id from list_uploads (kind audio). At least 1
`memberId`	body	integer	optional	An existing sound layer. At least 1
`volume`	body	number	optional	Volume of a newly added sound layer (default 0.3). 0 to 1

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Clear drawing

POST/api/v1/overlays/{overlayId}/members/{memberId}/drawing/clear

ON AIR: clears every stroke on a drawing layer right away (yours and viewers' strokes). Cannot be undone.

Scope: actions:fire (Trigger widgets on air) · MCP tool: clear_drawing · Notes: destructive, needs confirmation in MCP

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

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/drawing/clear" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/drawing/clear`, {
  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();

Let viewers draw

POST/api/v1/overlays/{overlayId}/drawing/viewers/enable

Lets viewers draw on the stream: adds the drawing layer when the overlay has none and turns on the viewer drawing link (the user shares it from the Draw panel in the editor). Returns the memberId of the drawing layer for clear_drawing and moderate_viewer_drawing. Owner only. The link itself is never returned.

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

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

Terminal

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

JavaScript

const overlayId = '<overlayId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/drawing/viewers/enable`, {
  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();

Get viewer drawing

GET/api/v1/overlays/{overlayId}/members/{memberId}/drawing/viewers

Tells whether viewer drawing is shared for a drawing layer (active) and lists the viewers who drew or are blocked (name, platform, blocked, stroke count, viewerKey for moderate_viewer_drawing). Owner only. Viewer names come from viewers.

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

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

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/drawing/viewers" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Moderate viewer drawing

POST/api/v1/overlays/{overlayId}/members/{memberId}/drawing/viewers

MODERATION: removes all viewer strokes (clear-viewer-strokes), or blocks or unblocks one viewer (viewerKey from get_viewer_drawing). Blocking also removes that viewer's strokes on air. Owner only.

Scope: actions:fire (Trigger widgets on air) · MCP tool: moderate_viewer_drawing · Notes: destructive, needs confirmation in MCP

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
`action`	body	`clear-viewer-strokes`, `block`, `unblock`	required
`viewerKey`	body	string	optional

Terminal

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

JavaScript

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

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

Get stream activity stats

GET/api/v1/overlays/{overlayId}/activity/stats

Returns the counts of the current stream session of the overlay owner's channel: follows, subs, cheers and bits, raids and raid viewers, tips, redemptions and hype trains since the session started. Use it for an overlay shared with you; for your own account without an overlay, get_account_activity_stats returns the same counts.

Scope: overlays:read (Read overlays) · MCP tool: get_activity_stats · 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>/activity/stats" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';

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

Get live data of a layer

GET/api/v1/overlays/{overlayId}/members/{memberId}/live-data

Reads the live data a layer shows: kind text-variables (latest follower and similar), stream-status, twitch-stats, youtube-stats, kofi-stats, community-feed (latest events and leaderboard) or media (what a media layer shows now, with slotId for move_media). Names and messages come from viewers.

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

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
`kind`	query	`text-variables`, `stream-status`, `twitch-stats`, `youtube-stats`, `kofi-stats`, `community-feed`, `media`	optional

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/live-data" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

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

Get YouTube queue

GET/api/v1/overlays/{overlayId}/members/{memberId}/youtube

Returns what the player layer plays now (video id, title, position, paused), the waiting queue, volume and mute. With videoId it also returns that video's public title.

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

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`videoId`	query	string	optional	YouTube video id (11 characters, e.g. dQw4w9WgXcQ)

Terminal

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

JavaScript

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

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

Play YouTube video now

POST/api/v1/overlays/{overlayId}/members/{memberId}/youtube/play

ON AIR: plays a YouTube video on the player layer right away (replaces what plays now; the queue stays).

Scope: actions:fire (Trigger widgets on air) · MCP tool: play_youtube_video · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`videoId`	body	string	required	YouTube video id (11 characters, e.g. dQw4w9WgXcQ)

Terminal

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

JavaScript

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

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

Queue YouTube video

POST/api/v1/overlays/{overlayId}/members/{memberId}/youtube/queue

ON AIR: adds a YouTube video to the end of the player queue; if nothing plays, it starts right away.

Scope: actions:fire (Trigger widgets on air) · MCP tool: queue_youtube_video · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`videoId`	body	string	required	YouTube video id (11 characters, e.g. dQw4w9WgXcQ)

Terminal

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

JavaScript

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

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

Control YouTube player

POST/api/v1/overlays/{overlayId}/members/{memberId}/youtube/control

ON AIR: skips to the next queued video, stops, pauses, resumes, mutes, unmutes or sets the volume (0 to 100) of the player layer right away.

Scope: actions:fire (Trigger widgets on air) · MCP tool: control_youtube · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`action`	body	`skip`, `stop`, `pause`, `resume`, `mute`, `unmute`, `volume`	required
`volume`	body	integer	optional	0 to 100

Terminal

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

JavaScript

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

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

Move queued YouTube video

PUT/api/v1/overlays/{overlayId}/members/{memberId}/youtube/queue/{itemId}/position

Moves a waiting video to another place in the player queue (toIndex 0 = next up).

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

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`itemId`	path	string	required	Queue item id from get_youtube_queue
`toIndex`	body	integer	required	0 to 99

Terminal

curl -X PUT "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/youtube/queue/<itemId>/position" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "toIndex": 1 }'

JavaScript

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

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

Remove queued YouTube video

DELETE/api/v1/overlays/{overlayId}/members/{memberId}/youtube/queue/{itemId}

DESTRUCTIVE: removes one waiting video from the player queue.

Scope: actions:fire (Trigger widgets on air) · MCP tool: remove_youtube_video · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1
`itemId`	path	string	required	Queue item id from get_youtube_queue

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/youtube/queue/<itemId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/youtube/queue/${itemId}`, {
  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();

Clear YouTube queue

DELETE/api/v1/overlays/{overlayId}/members/{memberId}/youtube/queue

DESTRUCTIVE: removes every waiting video from the player queue (what plays now keeps playing).

Scope: actions:fire (Trigger widgets on air) · MCP tool: clear_youtube_queue · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`memberId`	path	integer	required	The player layer. At least 1

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/youtube/queue" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/youtube/queue`, {
  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?