/api/public/v1/conversationsCreate a channel
Creates a channel with the token’s employee as its admin and first member, plus anyone named in `memberEmployeeIds`. It is created live: every member sees it in their list straight away, and it gets a folder in Vault like a channel made in the console. Channels only — a direct message or group chat is opened in the console. Members must be active employees of the caller’s own company. A channel is private unless `visibility` is PUBLIC, which lets anyone in the company find and join it. Names are not unique; check `list_conversations` first if a duplicate would confuse people.
Required scope
The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.
Request Body
| Property | Type | Description |
|---|---|---|
name | string | The channel’s name, up to 120 characters. |
description | string | What the channel is for, up to 500 characters. |
visibility | string | PRIVATE (the default) is invite-only; PUBLIC can be found and joined by anyone in the company. |
memberEmployeeIds | string[] | Employee ids to add besides you. An id that is not an active employee of your company is a 400 and nothing is created. |
curl -X POST "https://www.pxb.app/api/public/v1/conversations" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"name": "engineering",
"description": "Shipping things",
"visibility": "PUBLIC",
"memberEmployeeIds": [
"emp_44f1"
]
}'{
"message": "Channel created successfully!",
"content": {
"conversation": {
"id": "cnv_5150",
"referenceId": 88,
"type": "CHANNEL",
"title": "engineering",
"name": "engineering",
"topic": null,
"description": "Shipping things",
"visibility": "PUBLIC",
"isArchived": false,
"lastMessageAt": "2026-01-08T09:00:00.000Z",
"isSupport": false,
"isCrossCompany": false,
"memberEmployeeIds": [
"emp_12ab",
"emp_44f1"
],
"createdAt": "2026-01-08T09:00:00.000Z",
"isMember": true,
"unreadCount": 0,
"unreadThreadCount": 0,
"lastReadAt": null,
"markedUnread": false,
"isMuted": false,
"isFavorite": false
}
}
}{
"message": "One or more selected employees are invalid."
}In the console
The same thing done by hand, for anyone comparing the API against the screen they already use.