# Overlays API

Create, list, rename, resize and delete overlays.

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 overlays](#list-overlays) | `GET /overlays` | `overlays:read` |
| [Get overlay](#get-overlay) | `GET /overlays/{overlayId}` | `overlays:read` |
| [Create overlay](#create-overlay) | `POST /overlays` | `overlays:write` |
| [Rename or resize overlay](#rename-or-resize-overlay) | `PATCH /overlays/{overlayId}` | `overlays:write` |
| [Delete overlay](#delete-overlay) | `DELETE /overlays/{overlayId}` | `overlays:write` |
| [Duplicate overlay](#duplicate-overlay) | `POST /overlays/{overlayId}/duplicate` | `overlays:write` |

## Operations

### List overlays

```http Endpoint
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

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/overlays" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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) |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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) |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "width": 320 }'
```
@@ JavaScript
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
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
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
curl -X DELETE "https://pxstudio.cloud/api/v1/overlays/<overlayId>" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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

```http Endpoint
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 |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/duplicate" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
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();
```
:::