# History API

The change history of an overlay and undo.

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 overlay history](#list-overlay-history) | `GET /overlays/{overlayId}/history` | `overlays:read` |
| [Restore overlay history](#restore-overlay-history) | `POST /overlays/{overlayId}/history/{historyId}/restore` | `overlays:write` |

## Operations

### List overlay history

```http Endpoint
GET /api/v1/overlays/{overlayId}/history
```

Lists the last changes of an overlay (newest first, up to 50) with who made them. Each entry holds the state BEFORE its change: restore_history with an entry undoes that change and everything after it. History is only available to the overlay owner and editors with all edit rights.

**Scope:** `overlays:read` (Read overlays) · **MCP tool:** `list_history` · **Notes:** read only

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

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/overlays/<overlayId>/history" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const overlayId = '<overlayId>';

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

### Restore overlay history

```http Endpoint
POST /api/v1/overlays/{overlayId}/history/{historyId}/restore
```

DESTRUCTIVE: restores the overlay to the state before the chosen history entry, undoing that change and every later one (layers, scenes and settings). Send the historyRev from list_history as expectedHistoryRev; if the overlay changed since, it answers 409 history_conflict. Visible on air when the live scene changes.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `historyId` | path | string | required | History entry id (from list_history) |
| `expectedHistoryRev` | body | string | required | HistoryRev from list_history |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/history/<historyId>/restore" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "expectedHistoryRev": "..." }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';
const historyId = '<historyId>';

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