Community API

Viewers, loyalty points, ranks and rewards.

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 giveaway	`GET /bot/giveaway`	`bot:read`
List giveaway entries	`GET /bot/giveaway/entries`	`bot:read`
List past giveaways	`GET /bot/giveaway/history`	`bot:read`
Get giveaway defaults	`GET /bot/giveaway/defaults`	`bot:read`
Set giveaway defaults	`PATCH /bot/giveaway/defaults`	`bot:write`
Start giveaway	`POST /bot/giveaway`	`bot:write`
Draw giveaway winner	`POST /bot/giveaway/draw`	`bot:write`
Control giveaway	`POST /bot/giveaway/control`	`bot:write`
Remove giveaway entry	`POST /bot/giveaway/entries/remove`	`bot:write`
Cancel giveaway	`POST /bot/giveaway/cancel`	`bot:write`
Get loyalty settings	`GET /bot/loyalty`	`bot:read`
List loyalty leaderboard	`GET /bot/loyalty/top`	`bot:read`
Get loyalty viewer	`GET /bot/loyalty/viewers/{login}`	`bot:read`
Update loyalty settings	`PATCH /bot/loyalty`	`bot:write`
List loyalty rewards	`GET /bot/loyalty/rewards`	`bot:read`
Create loyalty reward	`POST /bot/loyalty/rewards`	`bot:write`
Update loyalty reward	`PATCH /bot/loyalty/rewards/{rewardId}`	`bot:write`
Delete loyalty reward	`DELETE /bot/loyalty/rewards/{rewardId}`	`bot:write`
Trigger loyalty reward	`POST /bot/loyalty/rewards/{rewardId}/trigger`	`bot:write`
Adjust loyalty points	`POST /bot/loyalty/adjust`	`bot:write`
List channel point actions	`GET /bot/channel-points`	`bot:read`
Create channel point action	`POST /bot/channel-points`	`bot:write`
Update channel point action	`PATCH /bot/channel-points/{rewardId}`	`bot:write`
Delete channel point action	`DELETE /bot/channel-points/{rewardId}`	`bot:write`
Test channel point action	`POST /bot/channel-points/{rewardId}/simulate`	`bot:write`

Operations

Get giveaway

GET/api/v1/bot/giveaway

Returns the running or last drawn PXStudioBot giveaway (phase, keyword, prize, entries, timer, winners and what each winner wrote in chat since the draw) and whether Twitch and Kick chat are ready for one. Winner names and chat lines come from viewers.

Scope: bot:read (Read bot settings) · MCP tool: get_giveaway · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/giveaway" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

List giveaway entries

GET/api/v1/bot/giveaway/entries

Lists the viewers in the running (or last drawn) giveaway with their tickets and whether they can win. Logins come from viewers.

Scope: bot:read (Read bot settings) · MCP tool: list_giveaway_entries · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`q`	query	string	optional	Login prefix. Up to 64 characters
`filter`	query	`all`, `subs`, `vips`, `followers`, `ineligible`	optional
`platform`	query	`twitch`, `kick`	optional
`limit`	query	integer	optional	1 to 100
`after`	query	integer	optional	NextAfter of the previous page. At least 1

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/giveaway/entries" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

List past giveaways

GET/api/v1/bot/giveaway/history

Lists finished PXStudioBot giveaways (newest first) with prize, entries and winners; with giveawayId one giveaway with its first entries. Names come from viewers.

Scope: bot:read (Read bot settings) · MCP tool: list_giveaway_history · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`giveawayId`	query	string	optional
`limit`	query	integer	optional	1 to 50
`before`	query	integer	optional	At least 1

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/giveaway/history" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Get giveaway defaults

GET/api/v1/bot/giveaway/defaults

Returns the saved giveaway defaults that every new giveaway starts with (keyword, prize, duration, winners, claim time, entry rules, ticket weights, platforms).

Scope: bot:read (Read bot settings) · MCP tool: get_giveaway_defaults · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/giveaway/defaults" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Set giveaway defaults

PATCH/api/v1/bot/giveaway/defaults

Changes the saved giveaway defaults (send only what changes; replace true replaces all defaults with the given ones). Running giveaways are not affected.

Scope: bot:write (Change the bot) · MCP tool: set_giveaway_defaults

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`keyword`	body	string	optional	Word viewers type to join, e.g. join for !join. Up to 33 characters
`matchMode`	body	`command`, `word`, `redeem`, `any`	optional	Command = !keyword, word = the keyword anywhere, redeem = a channel point reward, any = all three
`prize`	body	string	optional	Up to 120 characters
`durationMin`	body	integer	optional	Minutes until entries close (0 = until you close it). 0 to 120
`winnersMax`	body	integer	optional	1 to 10
`claimSeconds`	body	integer	optional	Seconds a winner has to answer in chat (0 = no claim, else 30 to 180). 0 to 180
`platforms`	body	array of `twitch`, `kick`	optional	Up to 2 items
`minRole`	body	`everyone`, `sub`, `vip`, `mod`, `broadcaster`	optional	Lowest role allowed (everyone, sub, vip, mod, broadcaster)
`weighting`	body	object	optional	Extra tickets per role
`gates`	body	object	optional
`rewardId`	body	string	optional	Channel point reward id for matchMode redeem. Up to 64 characters
`confirmJoins`	body	boolean	optional
`showDisclaimer`	body	boolean	optional
`reminderEveryMin`	body	integer	optional	0 to 60
`autoRerollMax`	body	integer	optional	0 to 10
`replace`	body	boolean	optional	Replace all saved defaults instead of merging

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/bot/giveaway/defaults" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "...", "matchMode": "command" }'

JavaScript

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

Start giveaway

POST/api/v1/bot/giveaway

PUBLIC: starts a PXStudioBot giveaway in your chat right away; fields left out come from the saved defaults. Viewers join with the keyword.

Scope: bot:write (Change the bot) · MCP tool: start_giveaway · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`keyword`	body	string	optional	Word viewers type to join, e.g. join for !join. Up to 33 characters
`matchMode`	body	`command`, `word`, `redeem`, `any`	optional	Command = !keyword, word = the keyword anywhere, redeem = a channel point reward, any = all three
`prize`	body	string	optional	Up to 120 characters
`durationMin`	body	integer	optional	Minutes until entries close (0 = until you close it). 0 to 120
`winnersMax`	body	integer	optional	1 to 10
`claimSeconds`	body	integer	optional	Seconds a winner has to answer in chat (0 = no claim, else 30 to 180). 0 to 180
`platforms`	body	array of `twitch`, `kick`	optional	Up to 2 items
`minRole`	body	`everyone`, `sub`, `vip`, `mod`, `broadcaster`	optional	Lowest role allowed (everyone, sub, vip, mod, broadcaster)
`weighting`	body	object	optional	Extra tickets per role
`gates`	body	object	optional
`rewardId`	body	string	optional	Channel point reward id for matchMode redeem. Up to 64 characters
`confirmJoins`	body	boolean	optional
`showDisclaimer`	body	boolean	optional
`reminderEveryMin`	body	integer	optional	0 to 60
`autoRerollMax`	body	integer	optional	0 to 10

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/giveaway" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "...", "matchMode": "command" }'

JavaScript

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

Draw giveaway winner

POST/api/v1/bot/giveaway/draw

PUBLIC: draws the winner(s) of the running giveaway; the bot announces them in chat right away. Winner names come from viewers.

Scope: bot:write (Change the bot) · MCP tool: draw_giveaway_winner · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`count`	body	integer	optional	1 to 10

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/giveaway/draw" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "count": 1 }'

JavaScript

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

Control giveaway

POST/api/v1/bot/giveaway/control

PUBLIC: pauses, resumes or closes entries of the running giveaway, rerolls a winner (the last one, or the winner named by login), draws the next winner or marks a winner as claimed (claim needs login). The bot posts it in chat.

Scope: bot:write (Change the bot) · MCP tool: control_giveaway · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`action`	body	`pause`, `resume`, `close`, `reroll`, `next`, `claim`	required
`login`	body	string	optional	Viewer login (chat name), with or without @. Up to 64 characters

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/giveaway/control" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "pause" }'

JavaScript

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

Remove giveaway entry

POST/api/v1/bot/giveaway/entries/remove

MODERATION: removes a viewer from the running giveaway (they cannot win; a drawn winner loses the win).

Scope: bot:write (Change the bot) · MCP tool: remove_giveaway_entry · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`login`	body	string	required	Viewer login (chat name), with or without @. Up to 64 characters
`platform`	body	`twitch`, `kick`	optional

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/giveaway/entries/remove" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "login": "..." }'

JavaScript

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

Cancel giveaway

POST/api/v1/bot/giveaway/cancel

DESTRUCTIVE: cancels the running giveaway without a winner; the entries are gone and the bot says so in chat.

Scope: bot:write (Change the bot) · MCP tool: cancel_giveaway · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/giveaway/cancel" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Get loyalty settings

GET/api/v1/bot/loyalty

Returns the loyalty points settings: point name, watchtime and chat points, event bonuses, platforms, slots, transfers, loans and rank badges.

Scope: bot:read (Read bot settings) · MCP tool: get_loyalty · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/loyalty" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

List loyalty leaderboard

GET/api/v1/bot/loyalty/top

Lists the viewers with the most loyalty points. Logins come from viewers.

Scope: bot:read (Read bot settings) · MCP tool: list_loyalty_leaderboard · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`limit`	query	integer	optional	1 to 100

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/loyalty/top" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Get loyalty viewer

GET/api/v1/bot/loyalty/viewers/{login}

Returns the loyalty points, watchtime, streak and rank of one viewer (on every platform where they have an account, or on platform).

Scope: bot:read (Read bot settings) · MCP tool: get_loyalty_viewer · Notes: read only

Name	In	Type	Required	Description
`login`	path	string	required	Viewer login (chat name), with or without @. Up to 64 characters
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`platform`	query	`twitch`, `kick`, `youtube`	optional

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/loyalty/viewers/<login>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const login = '<login>';

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

Update loyalty settings

PATCH/api/v1/bot/loyalty

PUBLIC: changes the loyalty points settings (send only what changes; lists replace the old list). Viewers earn, spend and see points by the new rules right away.

Scope: bot:write (Change the bot) · MCP tool: update_loyalty_settings · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`enabled`	body	boolean	optional
`pointName`	body	string	optional	Up to 20 characters
`watchtime`	body	object	optional
`chatBonus`	body	object	optional
`eventBonus`	body	object	optional
`platforms`	body	object	optional
`gambling`	body	object	optional
`transfer`	body	object	optional
`loan`	body	object	optional
`ranks`	body	array of object	optional	Rank badges (replaces the list). Up to 32 items

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/bot/loyalty" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "pointName": "..." }'

JavaScript

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

List loyalty rewards

GET/api/v1/bot/loyalty/rewards

Lists the loyalty rewards viewers can redeem with !redeem (cost, chat text, action).

Scope: bot:read (Read bot settings) · MCP tool: list_loyalty_rewards · Notes: read only

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/loyalty/rewards" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Create loyalty reward

POST/api/v1/bot/loyalty/rewards

PUBLIC: adds a loyalty reward viewers can redeem with !redeem right away, with an optional action (widget command, scene, spot, timeout of the redeemer, extra points or a bot command).

Scope: bot:write (Change the bot) · MCP tool: create_loyalty_reward · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`name`	body	string	required	Name viewers use with !redeem. Up to 32 characters
`cost`	body	integer	required	1 to 1000000000
`sayTemplate`	body	string	optional	What the bot says on a redeem ({user}, {reward}, {cost}). Up to 200 characters
`enabled`	body	boolean	optional
`action`	body	object	optional

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/loyalty/rewards" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "cost": 1 }'

JavaScript

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

Update loyalty reward

PATCH/api/v1/bot/loyalty/rewards/{rewardId}

PUBLIC: changes a loyalty reward (send only what changes; enabled alone switches it on or off). Viewers see the change right away.

Scope: bot:write (Change the bot) · MCP tool: update_loyalty_reward · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	At least 1
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`name`	body	string	optional	Name viewers use with !redeem. Up to 32 characters
`cost`	body	integer	optional	1 to 1000000000
`sayTemplate`	body	string	optional	What the bot says on a redeem ({user}, {reward}, {cost}). Up to 200 characters
`enabled`	body	boolean	optional
`action`	body	object	optional

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/bot/loyalty/rewards/<rewardId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "cost": 1 }'

JavaScript

const rewardId = '<rewardId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/bot/loyalty/rewards/${rewardId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: "...", cost: 1 }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Delete loyalty reward

DELETE/api/v1/bot/loyalty/rewards/{rewardId}

DESTRUCTIVE: deletes a loyalty reward; viewers can no longer redeem it.

Scope: bot:write (Change the bot) · MCP tool: delete_loyalty_reward · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	At least 1
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/bot/loyalty/rewards/<rewardId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const rewardId = '<rewardId>';

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

Trigger loyalty reward

POST/api/v1/bot/loyalty/rewards/{rewardId}/trigger

ON AIR: runs a loyalty reward now. preview runs its action without points; redeem redeems it for a viewer (login) and takes their points.

Scope: bot:write (Change the bot) · MCP tool: trigger_loyalty_reward · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	At least 1
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`mode`	body	`preview`, `redeem`	required
`login`	body	string	optional	Viewer login (chat name), with or without @. Up to 64 characters
`platform`	body	`twitch`, `kick`, `youtube`	optional

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/loyalty/rewards/<rewardId>/trigger" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "preview" }'

JavaScript

const rewardId = '<rewardId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/bot/loyalty/rewards/${rewardId}/trigger`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mode: "preview" }),
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Adjust loyalty points

POST/api/v1/bot/loyalty/adjust

PUBLIC: gives (positive delta) or takes (negative delta) loyalty points of a viewer; their balance and the leaderboard change right away. reason (optional) is kept in the overlay owner's team activity log when a team member adjusts points.

Scope: bot:write (Change the bot) · MCP tool: adjust_loyalty_points · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`overlayId`	query	string	optional	Act on the bot of this overlay's owner. Only for overlays shared with you; leave out for your own bot. Up to 64 characters
`login`	body	string	required	Viewer login (chat name), with or without @. Up to 64 characters
`platform`	body	`twitch`, `kick`, `youtube`	optional
`delta`	body	integer	required	-1000000 to 1000000
`reason`	body	string	optional	Why, e.g. "won the quiz". Up to 100 characters

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/loyalty/adjust" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "login": "...", "delta": 1 }'

JavaScript

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

List channel point actions

GET/api/v1/bot/channel-points

Lists what happens when viewers redeem Twitch channel point rewards (your actions per reward), whether Twitch allows reading redemptions, and the last redemptions (viewer names and texts come from viewers). Only for your own account.

Scope: bot:read (Read bot settings) · MCP tool: list_channel_point_rewards · Notes: read only

Terminal

curl -X GET "https://pxstudio.cloud/api/v1/bot/channel-points" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

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

Create channel point action

POST/api/v1/bot/channel-points

PUBLIC: adds what happens when viewers redeem a Twitch channel point reward (match by reward id or title): fire a widget command, put a scene on air, move a layer into a spot, show a media favorite, post in chat or change the stream title or category. Only for your own account.

Scope: bot:write (Change the bot) · MCP tool: create_channel_point_reward · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`name`	body	string	required	Up to 60 characters
`match`	body	object	required	Which Twitch channel point reward triggers it: by reward id (from the recent redemptions) or by title
`action`	body	object	required
`enabled`	body	boolean	optional
`cooldownSec`	body	integer	optional	0 to 86400

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/channel-points" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "match": {}, "action": {} }'

JavaScript

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

Update channel point action

PATCH/api/v1/bot/channel-points/{rewardId}

PUBLIC: changes a channel point action (send only what changes; enabled alone switches it on or off). It applies to the next redemption. Only for your own account.

Scope: bot:write (Change the bot) · MCP tool: update_channel_point_reward · Notes: needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	Channel point action id from list_channel_point_rewards. At least 1
`name`	body	string	optional	Up to 60 characters
`match`	body	object	optional	Which Twitch channel point reward triggers it: by reward id (from the recent redemptions) or by title
`action`	body	object	optional
`enabled`	body	boolean	optional
`cooldownSec`	body	integer	optional	0 to 86400

Terminal

curl -X PATCH "https://pxstudio.cloud/api/v1/bot/channel-points/<rewardId>" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "match": {} }'

JavaScript

const rewardId = '<rewardId>';

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

Delete channel point action

DELETE/api/v1/bot/channel-points/{rewardId}

DESTRUCTIVE: deletes a channel point action; redemptions of that reward do nothing in PX Studio anymore. The reward on Twitch stays. Only for your own account.

Scope: bot:write (Change the bot) · MCP tool: delete_channel_point_reward · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	At least 1

Terminal

curl -X DELETE "https://pxstudio.cloud/api/v1/bot/channel-points/<rewardId>" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const rewardId = '<rewardId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/bot/channel-points/${rewardId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();

Test channel point action

POST/api/v1/bot/channel-points/{rewardId}/simulate

ON AIR: runs a channel point action once as if "Test Viewer" redeemed it; its action shows on stream right away. Only for your own account.

Scope: bot:write (Change the bot) · MCP tool: simulate_channel_point_reward · Notes: destructive, needs confirmation in MCP

Name	In	Type	Required	Description
`rewardId`	path	integer	required	At least 1

Terminal

curl -X POST "https://pxstudio.cloud/api/v1/bot/channel-points/<rewardId>/simulate" \
  -H "Authorization: Bearer $PX_TOKEN"

JavaScript

const rewardId = '<rewardId>';

const res = await fetch(`https://pxstudio.cloud/api/v1/bot/channel-points/${rewardId}/simulate`, {
  method: 'POST',
  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?