Settings API

Read and change the settings of a widget.

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
Get layer settings	`GET /overlays/{overlayId}/members/{memberId}/fields`	`overlays:read`
Change layer settings	`PATCH /overlays/{overlayId}/members/{memberId}/fields`	`fields:write`
Add list entries	`POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items`	`fields:write`
Change a list entry	`PATCH /overlays/{overlayId}/members/{memberId}/fields/{field}/items`	`fields:write`
Remove list entries	`POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items/remove`	`fields:write`
Reorder a list entry	`POST /overlays/{overlayId}/members/{memberId}/fields/{field}/items/move`	`fields:write`

Operations

Get layer settings

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

Terminal

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

JavaScript

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

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

Terminal

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

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

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

Terminal

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

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

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}

Terminal

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

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

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

Terminal

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

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

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

Terminal

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

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

Was this page helpful?