Widgets API
The widget catalog and the looks of a widget.
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 widgets | GET /widgets | overlays:read |
| Get widget | GET /widgets/{slug} | overlays:read |
| List presets and look kits | GET /presets | overlays:read |
Operations
List widgets
/api/v1/widgetsLists the widgets you can add as layers (slug, name, kind, availability, looks). With overlayId, availability is computed for that overlay's owner. Use get_widget for field definitions, commands and actions.
Scope: overlays:read (Read overlays) · MCP tool: list_widgets · Notes: read only
| Name | In | Type | Required | Description |
|---|---|---|---|---|
overlayId | query | string | optional | Optional: compute availability for this overlay (shared overlays use the owner's unlocks). Up to 64 characters |
curl -X GET "https://pxstudio.cloud/api/v1/widgets" \
-H "Authorization: Bearer $PX_TOKEN"const res = await fetch('https://pxstudio.cloud/api/v1/widgets', {
headers: {
Authorization: `Bearer ${process.env.PX_TOKEN}`,
},
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();Get widget
/api/v1/widgets/{slug}Returns one widget's field definitions (key, type, default, options, min/max), looks, declared chat commands and canvas actions.
Scope: overlays:read (Read overlays) · MCP tool: get_widget · Notes: read only
| Name | In | Type | Required | Description |
|---|---|---|---|---|
slug | path | string | required | Up to 80 characters |
overlayId | query | string | optional | Optional: availability for this overlay's owner. Up to 64 characters |
curl -X GET "https://pxstudio.cloud/api/v1/widgets/<slug>" \
-H "Authorization: Bearer $PX_TOKEN"const slug = '<slug>';
const res = await fetch(`https://pxstudio.cloud/api/v1/widgets/${slug}`, {
headers: {
Authorization: `Bearer ${process.env.PX_TOKEN}`,
},
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();List presets and look kits
/api/v1/presetsLists the New-Overlay presets (use with create_overlay) and the look kits (color/font tokens and per-widget settings values; use with add_member lookKit).
Scope: overlays:read (Read overlays) · MCP tool: list_presets · Notes: read only
curl -X GET "https://pxstudio.cloud/api/v1/presets" \
-H "Authorization: Bearer $PX_TOKEN"const res = await fetch('https://pxstudio.cloud/api/v1/presets', {
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?