Login / Register
POST
/api/public/v1/conversations

Create 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.

threads:write

Request Body

PropertyTypeDescription
namestringThe channel’s name, up to 120 characters.
descriptionstringWhat the channel is for, up to 500 characters.
visibilitystringPRIVATE (the default) is invite-only; PUBLIC can be found and joined by anyone in the company.
memberEmployeeIdsstring[]Employee ids to add besides you. An id that is not an active employee of your company is a 400 and nothing is created.
POSTExample request
curl
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"
    ]
  }'
200Example response
json
{
  "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
    }
  }
}
400Example response
json
{
  "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.

Threads
/threads
  1. Choose New conversation, then New channel.
  2. Name it and add people.