Overlays API

Create, list, rename, resize and delete overlays.

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 overlays	`GET /overlays`	`overlays:read`
Get overlay	`GET /overlays/{overlayId}`	`overlays:read`
Create overlay	`POST /overlays`	`overlays:write`
Rename or resize overlay	`PATCH /overlays/{overlayId}`	`overlays:write`
Delete overlay	`DELETE /overlays/{overlayId}`	`overlays:write`
Duplicate overlay	`POST /overlays/{overlayId}/duplicate`	`overlays:write`

Operations

List overlays

GET/api/v1/overlays

Lists the overlays you own and the overlays shared with you as an editor, with your role and permissions on each.

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

Terminal

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

JavaScript

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

Get overlay

GET/api/v1/overlays/{overlayId}

Returns the full state of one overlay: canvas size, layers (position, stacking, visibility, settings values, commands), and scenes with each layer's per-scene state. A layer's w and h are its measured size on the canvas in design pixels (after scale, rotation and crop); they are missing until the editor has measured the layer.

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

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`fields`	query	boolean	optional	Include each layer's settings values (default true)

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Create overlay

POST/api/v1/overlays

Creates a new overlay, either blank, from a preset (list_presets), from a quick-start template (list_templates) or with the starter kit (starter:true, three example layers). Look presets create a full scene set (Starting Soon, Live, BRB, Ending). Supports the Idempotency-Key header.

Scope: overlays:write (Design overlays) · MCP tool: create_overlay · Notes: supports Idempotency-Key

Name	In	Type	Required	Description
`name`	body	string	optional	Up to 40 characters
`width`	body	integer	optional	Output width in px (default 1920). 320 to 7680
`height`	body	integer	optional	Output height in px (default 1080). 320 to 7680
`preset`	body	string	optional	Preset id from list_presets (e.g. "blank", "look-neon"). Up to 64 characters
`presetOptions`	body	object	optional	Toggle options of the preset (keys from list_presets)
`template`	body	string	optional	Template id from list_templates. Up to 64 characters
`starter`	body	boolean	optional	True seeds the starter kit (three example layers)

Terminal

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

JavaScript

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

Rename or resize overlay

PATCH/api/v1/overlays/{overlayId}

Renames an overlay and/or changes its output resolution. Resizing never moves layers.

Scope: overlays:write (Design overlays) · MCP tool: update_overlay

Name	In	Type	Required	Description
`overlayId`	path	string	required	Overlay id (from list_overlays). Up to 64 characters
`name`	body	string	optional	Up to 40 characters
`width`	body	integer	optional	320 to 7680
`height`	body	integer	optional	320 to 7680

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

Delete overlay

DELETE/api/v1/overlays/{overlayId}

DESTRUCTIVE: permanently deletes an overlay you own, with all its layers and scenes. OBS sources pointing at it go blank. Owner only. Cannot be undone.

Scope: overlays:write (Design overlays) · MCP tool: delete_overlay · Notes: destructive, needs confirmation in MCP

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

Terminal

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

JavaScript

const overlayId = '<overlayId>';

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

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

Copies an overlay you own with all its layers, groups and scenes under "<name> copy". The copy is a new overlay with its own OBS link; the original stays unchanged. Owner only, counts against your overlay limit.

Scope: overlays:write (Design overlays) · MCP tool: duplicate_overlay

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>/duplicate" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const overlayId = '<overlayId>';

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

Was this page helpful?