History API

The change history of an overlay and undo.

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

Operations

List overlay history

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

Terminal

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

JavaScript

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

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

Terminal

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

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();

Was this page helpful?