# Packs API

Overlay packs and presets.

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 packs](#list-packs) | `GET /packs` | `overlays:read` |
| [Get pack](#get-pack) | `GET /packs/{packId}` | `overlays:read` |
| [Change pack look](#change-pack-look) | `PUT /packs/{packId}/theme` | `overlays:write` |
| [List marketplace](#list-marketplace) | `GET /marketplace` | `overlays:read` |

## Operations

### List packs

```http Endpoint
GET /api/v1/packs
```

Lists the overlay packs you own (id, name, accent color, when you got it).

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

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/packs" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/packs', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Get pack

```http Endpoint
GET /api/v1/packs/{packId}
```

Returns one pack: its scenes (names only; the OBS links stay on the pack page) and its current look (identity, colors, texts, countdown, switches) to change with set_pack_theme. Values that could be secret show as "[hidden]".

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `packId` | path | string | required | Pack id (from list_packs). Up to 80 characters |

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

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

### Change pack look

```http Endpoint
PUT /api/v1/packs/{packId}/theme
```

Changes the look of a pack (keys from get_pack theme): the values you send are deep-merged into the current look, null removes a key, lists replace the whole list. Values shown as "[hidden]" cannot be changed here. Pack scenes in OBS show the new look on their next reload.

**Scope:** `overlays:write` (Design overlays) · **MCP tool:** `set_pack_theme`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `packId` | path | string | required | Pack id (from list_packs). Up to 80 characters |
| `theme` | body | object | required | Only the values to change, at the same path as in get_pack, e.g. {"look": {"accent": "#ff5c39"}} or {"identity": {"name": "YourName"}} |

::: tabs
@@ cURL
```bash
curl -X PUT "https://pxstudio.cloud/api/v1/packs/<packId>/theme" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "theme": {} }'
```
@@ JavaScript
```js
const packId = '<packId>';

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

### List marketplace

```http Endpoint
GET /api/v1/marketplace
```

Lists the marketplace catalog: widgets (free or premium, price, whether you have them), bundles, style packs and overlay packs. Buying happens on the billing page. Descriptions are marketplace content.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | `all`, `widgets`, `bundles`, `stylePacks`, `overlayPacks` | optional |  |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/marketplace" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/marketplace', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::