# Settings API

Read and change the settings 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 |
| --- | --- | --- |
| [Get layer settings](#get-layer-settings) | `GET /overlays/{overlayId}/members/{memberId}/fields` | `overlays:read` |
| [Change layer settings](#change-layer-settings) | `PATCH /overlays/{overlayId}/members/{memberId}/fields` | `fields:write` |
| [Add list entries](#add-list-entries) | `POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items` | `fields:write` |
| [Change a list entry](#change-a-list-entry) | `PATCH /overlays/{overlayId}/members/{memberId}/fields/{field}/items` | `fields:write` |
| [Remove list entries](#remove-list-entries) | `POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items/remove` | `fields:write` |
| [Reorder a list entry](#reorder-a-list-entry) | `POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items/move` | `fields:write` |

## Operations

### Get layer settings

```http Endpoint
GET /api/v1/overlays/{overlayId}/members/{memberId}/fields
```

Returns the settings values of one layer, the version to send back as expectedVersion, and the field definitions (type, default, options) of its widget. Dropdown settings are summed up in dropdowns.<key> as option key -> label; update_member_fields takes the key. List settings carry their item shape (itemSchema, maxItems; summary in lists.<key>.shape) and items with ids for add_list_items, update_list_item, remove_list_items and move_list_item.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |

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

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

### Change layer settings

```http Endpoint
PATCH /api/v1/overlays/{overlayId}/members/{memberId}/fields
```

Changes settings of one layer (only the keys you send). Values are checked against the widget's field definitions; keys the widget does not have are listed as ignored (none known: 400 unknown_field). A dropdown takes the option key (e.g. "miami"), not its label; a value that is not an option answers 422 invalid_option with the allowed options (key and label), a value of the wrong type (number, color, true/false) 422 invalid_value, and nothing is changed. A list setting replaces the whole list and must match its item shape from get_member_fields, otherwise 422 list_invalid names the field, the expected shape and the reasons and nothing is changed; the answer counts the saved entries in lists.<key>.count. To add, change, remove or reorder single entries prefer add_list_items, update_list_item, remove_list_items and move_list_item. With expectedVersion, a concurrent change answers 409 field_conflict instead of overwriting. Visible on air if the layer is shown.

**Scope:** `fields:write` (Change widget settings) · **MCP tool:** `update_member_fields`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |
| `values` | body | object | required | Changed settings, e.g. {"text": "Hello", "fontSize": 64} |
| `expectedVersion` | body | integer | optional | Optional: the version from get_member_fields. At least 0 |

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

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

### Add list entries

```http Endpoint
POST /api/v1/overlays/{overlayId}/members/{memberId}/fields/{field}/items
```

Adds entries to a list setting of one layer (e.g. challenges of a Challenges board), at the end or at position. Entries follow the item shape from get_member_fields; plain text fills the first text key. If an entry does not fit (wrong keys, empty or duplicate name, list full) nothing is added and 422 list_invalid names the reasons. Returns the saved list and its count. Visible on air if the layer is shown.

**Scope:** `fields:write` (Change widget settings) · **MCP tool:** `add_list_items`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |
| `field` | path | string | required | Name of the list setting, e.g. "games" (get_member_fields: fields with type list). Up to 64 characters |
| `items` | body | array of object or string | required | Entries to add, in order. Up to 50 items |
| `position` | body | integer | optional | Optional 0-based insert position; default is the end. 0 to 49 |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/fields/<field>/items" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "items": [] }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';
const memberId = '<memberId>';
const field = '<field>';

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

### Change a list entry

```http Endpoint
PATCH /api/v1/overlays/{overlayId}/members/{memberId}/fields/{field}/items
```

Changes one entry of a list setting (only the item keys you send), found by itemId or 0-based index. A new name on a Challenges entry starts its progress again. Returns the saved list and its count; a value that does not fit answers 422 list_invalid and nothing is changed.

**Scope:** `fields:write` (Change widget settings) · **MCP tool:** `update_list_item`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |
| `field` | path | string | required | Name of the list setting, e.g. "games" (get_member_fields: fields with type list). Up to 64 characters |
| `itemId` | body | string | optional | Item id from get_member_fields values (e.g. "item-2"). Up to 40 characters |
| `index` | body | integer | optional | 0-based position in the list (0 = first). 0 to 49 |
| `values` | body | object | required | Changed item keys, e.g. {"target": 3} |

::: tabs
@@ cURL
```bash
curl -X PATCH "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/fields/<field>/items" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "values": {} }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';
const memberId = '<memberId>';
const field = '<field>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/fields/${field}/items`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ values: {} }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Remove list entries

```http Endpoint
POST /api/v1/overlays/{overlayId}/members/{memberId}/fields/{field}/items/remove
```

Removes entries of a list setting, found by itemIds or 0-based indexes (all must exist, otherwise 404 item_not_found and nothing changes). Undo restores them from the overlay history. Returns the saved list and its count.

**Scope:** `fields:write` (Change widget settings) · **MCP tool:** `remove_list_items`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |
| `field` | path | string | required | Name of the list setting, e.g. "games" (get_member_fields: fields with type list). Up to 64 characters |
| `itemIds` | body | array of string | optional | Up to 50 items |
| `indexes` | body | array of integer | optional | Up to 50 items |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/fields/<field>/items/remove" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": [], "indexes": [] }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';
const memberId = '<memberId>';
const field = '<field>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/fields/${field}/items/remove`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ itemIds: [], indexes: [] }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Reorder a list entry

```http Endpoint
POST /api/v1/overlays/{overlayId}/members/{memberId}/fields/{field}/items/move
```

Moves one entry of a list setting (by itemId or 0-based index) to the 0-based position to. Returns the saved list and its count.

**Scope:** `fields:write` (Change widget settings) · **MCP tool:** `move_list_item`

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays). Up to 64 characters |
| `memberId` | path | integer | required | Layer (member) id (from get_overlay or list_members). At least 1 |
| `field` | path | string | required | Name of the list setting, e.g. "games" (get_member_fields: fields with type list). Up to 64 characters |
| `itemId` | body | string | optional | Item id from get_member_fields values (e.g. "item-2"). Up to 40 characters |
| `index` | body | integer | optional | 0-based position in the list (0 = first). 0 to 49 |
| `to` | body | integer | required | New 0-based position (0 = first). 0 to 49 |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/members/<memberId>/fields/<field>/items/move" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": 1 }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';
const memberId = '<memberId>';
const field = '<field>';

const res = await fetch(`https://pxstudio.cloud/api/v1/overlays/${overlayId}/members/${memberId}/fields/${field}/items/move`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: 1 }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::