# Widgets API

The widget catalog and the looks of a widget.

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 widgets](#list-widgets) | `GET /widgets` | `overlays:read` |
| [Get widget](#get-widget) | `GET /widgets/{slug}` | `overlays:read` |
| [List presets and look kits](#list-presets-and-look-kits) | `GET /presets` | `overlays:read` |

## Operations

### List widgets

```http Endpoint
GET /api/v1/widgets
```

Lists 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 |

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

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

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

```http Endpoint
GET /api/v1/presets
```

Lists 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

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