Scenes API

Scenes of an overlay: create, prepare in preview and put them live.

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 scenes	`GET /overlays/{overlayId}/scenes`	`overlays:read`
Create scene	`POST /overlays/{overlayId}/scenes`	`scenes:write`
Rename scene or set its transition	`PATCH /overlays/{overlayId}/scenes/{sceneId}`	`scenes:write`
Delete scene	`DELETE /overlays/{overlayId}/scenes/{sceneId}`	`scenes:write`
Duplicate scene	`POST /overlays/{overlayId}/scenes/{sceneId}/duplicate`	`scenes:write`
Put scene on air	`POST /overlays/{overlayId}/scenes/{sceneId}/golive`	`scenes:golive`
Create preview of a scene	`POST /overlays/{overlayId}/scenes/{sceneId}/preview`	`scenes:write`
Take preview to program	`POST /overlays/{overlayId}/scenes/{sceneId}/take`	`scenes:golive`
Set a layer's state in a scene	`PATCH /overlays/{overlayId}/scenes/{sceneId}/members/{memberId}`	`scenes:write`
Reorder scenes	`PUT /overlays/{overlayId}/scenes/order`	`scenes:write`

Operations

List scenes

GET/api/v1/overlays/{overlayId}/scenes

Lists the scenes of an overlay and which one is live (activeSceneId).

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

JavaScript

const overlayId = '<overlayId>';

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

Create scene

POST/api/v1/overlays/{overlayId}/scenes

Creates a scene. mode "blank" (default) starts with every layer hidden; "snapshot" copies the current live state. A new scene is never live until you call go_live_scene. Supports the Idempotency-Key header.

Scope: scenes:write (Edit scenes) · MCP tool: create_scene · Notes: supports Idempotency-Key

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`name`	body	string	required	Up to 40 characters
`mode`	body	`blank`, `snapshot`	optional

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Rename scene or set its transition

PATCH/api/v1/overlays/{overlayId}/scenes/{sceneId}

Renames a scene and/or sets the transition used when it goes live (morph, fade, slide, zoom, cut; 200-2000 ms).

Scope: scenes:write (Edit scenes) · MCP tool: update_scene

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1
`name`	body	string	optional	Up to 40 characters
`transitionType`	body	`morph`, `fade`, `slide`, `zoom`, `cut`	optional
`transitionMs`	body	integer	optional	200 to 2000

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "transitionType": "morph" }'

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Delete scene

DELETE/api/v1/overlays/{overlayId}/scenes/{sceneId}

DESTRUCTIVE: deletes a scene. The live scene and the last scene cannot be deleted.

Scope: scenes:write (Edit scenes) · MCP tool: delete_scene · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1

Terminal

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

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Duplicate scene

POST/api/v1/overlays/{overlayId}/scenes/{sceneId}/duplicate

Copies a scene (every layer's position, stacking and visibility plus the transition) under "<name> copy". The copy is never live until you call go_live_scene; it counts against the scene limit.

Scope: scenes:write (Edit scenes) · MCP tool: duplicate_scene

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>/duplicate" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Put scene on air

POST/api/v1/overlays/{overlayId}/scenes/{sceneId}/golive

ON AIR: switches the live stream output to this scene immediately (viewers see it). Prefer preview_scene + take_preview_to_program, or edit scenes offline, when unsure. Preview scenes cannot go live directly.

Scope: scenes:golive (Switch scenes on air) · MCP tool: go_live_scene · Notes: destructive

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1
`transition`	body	`morph`, `fade`, `slide`, `zoom`, `cut`	optional	One-time transition override for this switch only

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>/golive" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transition": "morph" }'

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Create preview of a scene

POST/api/v1/overlays/{overlayId}/scenes/{sceneId}/preview

Creates an offline preview copy of a scene. Edit it safely (set_scene_member_state), then publish it with take_preview_to_program. Nothing changes on air.

Scope: scenes:write (Edit scenes) · MCP tool: preview_scene

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>/preview" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Take preview to program

POST/api/v1/overlays/{overlayId}/scenes/{sceneId}/take

ON AIR when the target scene is live: copies a preview scene into the scene it previews and removes the preview. If the target scene is live, viewers see the change immediately.

Scope: scenes:golive (Switch scenes on air) · MCP tool: take_preview_to_program · Notes: destructive

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

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>/take" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';
const sceneId = '<sceneId>';

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

Set a layer's state in a scene

PATCH/api/v1/overlays/{overlayId}/scenes/{sceneId}/members/{memberId}

Sets position, stacking and visibility of one layer inside one scene. For a scene that is NOT live this is an offline edit; for the live scene it changes the stream output immediately.

Scope: scenes:write (Edit scenes) · MCP tool: set_scene_member_state

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`sceneId`	path	integer	required	Scene id (from list_scenes). At least 1
`memberId`	path	integer	required	Layer (member) id (from get_overlay or list_members). At least 1
`layout`	body	object	optional	Placement in design-space pixels (canvas 1920 wide): x/y move the layer from the canvas center, scale 0.05-4, rot in degrees, opacity 0-1, optional crop (cropL/cropT/cropR/cropB in native px)
`z`	body	integer	optional	Stacking position (0 = bottom); other layers move to fill the gap. 0 to 1000
`hidden`	body	boolean	optional	Hide or show the layer (on the live output when this overlay is on air)
`expectedRev`	body	integer	optional	Optional guard: the scene rev (offline scene) or overlay rev (live scene) you last saw. At least 0

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/<sceneId>/members/<memberId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "layout": {}, "z": 1 }'

JavaScript

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

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

Reorder scenes

PUT/api/v1/overlays/{overlayId}/scenes/order

Sets the order of the scenes of an overlay (scene tabs, deck buttons and every scene list follow it). order must contain every scene id of the overlay exactly once, previews included; the first id becomes the first (leftmost) tab. Nothing changes on air.

Scope: scenes:write (Edit scenes) · MCP tool: reorder_scenes

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`order`	body	array of integer	required	All scene ids of the overlay in the new order (from list_scenes). Up to 100 items

Terminal

curl -X PUT "https://pxstudio.cloud/api/v1/overlays/<overlayId>/scenes/order" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "order": [] }'

JavaScript

const overlayId = '<overlayId>';

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

Was this page helpful?