# Chat API

Send messages to your chat and moderate it.

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 chat capabilities](#get-chat-capabilities) | `GET /overlays/{overlayId}/chat` | `overlays:read` |
| [Send chat message](#send-chat-message) | `POST /overlays/{overlayId}/chat/messages` | `chat:write` |
| [Moderate chat](#moderate-chat) | `POST /overlays/{overlayId}/chat/moderation` | `chat:moderate` |
| [Get chat mode](#get-chat-mode) | `GET /overlays/{overlayId}/chat/mode` | `overlays:read` |
| [Set chat mode](#set-chat-mode) | `PUT /overlays/{overlayId}/chat/mode` | `chat:moderate` |

## Operations

### Get chat capabilities

```http Endpoint
GET /api/v1/overlays/{overlayId}/chat
```

Returns for Twitch, Kick and YouTube whether the overlay owner's chat is connected and whether you can send messages, moderate and change chat modes there (null = only the platform knows).

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays); its owner's channels are the chat. Up to 64 characters |

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

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

### Send chat message

```http Endpoint
POST /api/v1/overlays/{overlayId}/chat/messages
```

PUBLIC: posts a message as your own account in the overlay owner's chat on Twitch, Kick and/or YouTube (all platforms where you can send when platforms is left out; YouTube only while the stream is live). Viewers see it right away.

**Scope:** `chat:write` (Send chat messages) · **MCP tool:** `send_chat_message` · **Notes:** needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays); its owner's channels are the chat. Up to 64 characters |
| `text` | body | string | required | Up to 500 characters |
| `platforms` | body | array of `twitch`, `kick`, `youtube` | optional | Up to 3 items |

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

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

### Moderate chat

```http Endpoint
POST /api/v1/overlays/{overlayId}/chat/moderation
```

MODERATION: deletes a chat message, times out, bans or unbans a viewer in the overlay owner's chat, with your own moderator rights there. delete needs msgId; timeout, ban and unban need targetUserId (both come from the chat panel).

**Scope:** `chat:moderate` (Moderate chat) · **MCP tool:** `moderate_chat` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays); its owner's channels are the chat. Up to 64 characters |
| `platform` | body | `twitch`, `kick`, `youtube` | required |  |
| `action` | body | `delete`, `timeout`, `ban`, `unban` | required |  |
| `msgId` | body | string | optional | Up to 64 characters |
| `targetUserId` | body | string | optional | Up to 64 characters |
| `targetName` | body | string | optional | Up to 40 characters |
| `durationS` | body | integer | optional | 1 to 1209600 |
| `reason` | body | string | optional | Up to 100 characters |

::: tabs
@@ cURL
```bash
curl -X POST "https://pxstudio.cloud/api/v1/overlays/<overlayId>/chat/moderation" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "twitch", "action": "delete" }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';

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

### Get chat mode

```http Endpoint
GET /api/v1/overlays/{overlayId}/chat/mode
```

Returns the chat modes of the overlay owner's Twitch chat: slow mode seconds, followers only (minutes or null), subscribers only, emote only and unique chat.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays); its owner's channels are the chat. Up to 64 characters |
| `platform` | query | `twitch` | optional |  |

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

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

### Set chat mode

```http Endpoint
PUT /api/v1/overlays/{overlayId}/chat/mode
```

MODERATION: changes chat modes of the overlay owner's Twitch chat right away (send only what changes): slowModeS (0 = off, 3 to 120), followersOnlyMin (null = off, minutes followed), subscribersOnly, emoteOnly, uniqueChat (no repeated messages).

**Scope:** `chat:moderate` (Moderate chat) · **MCP tool:** `set_chat_mode` · **Notes:** destructive, needs confirmation in MCP

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlayId` | path | string | required | Overlay id (from list_overlays); its owner's channels are the chat. Up to 64 characters |
| `platform` | body | `twitch` | required |  |
| `settings` | body | object | required |  |

::: tabs
@@ cURL
```bash
curl -X PUT "https://pxstudio.cloud/api/v1/overlays/<overlayId>/chat/mode" \
  -H "Authorization: Bearer $PX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "twitch", "settings": {} }'
```
@@ JavaScript
```js
const overlayId = '<overlayId>';

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