Skip to main content
POST
/
api
/
channels
/
create
curl -X POST "https://your-domain.com/api/channels/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "name": "announcements",
    "description": "Official announcements",
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      },
      {
        "principal_type": "role",
        "principal_id": "admin",
        "permission": "write"
      }
    ]
  }'

{
  "id": "ch_abc123",
  "user_id": "user_123",
  "type": "standard",
  "name": "announcements",
  "description": "Official announcements",
  "is_private": false,
  "data": null,
  "meta": null,
  "access_grants": [
    {
      "principal_type": "user",
      "principal_id": "*",
      "permission": "read"
    },
    {
      "principal_type": "role",
      "principal_id": "admin",
      "permission": "write"
    }
  ],
  "created_at": 1709567890123456789,
  "updated_at": 1709567890123456789,
  "updated_by": null,
  "archived_at": null,
  "archived_by": null,
  "deleted_at": null,
  "deleted_by": null
}
Creates a new channel. The type of channel determines who can create it and how it behaves:
  • dm - Direct message channel between users
  • group - Private group channel with invited members
  • standard - Public or restricted channel (admin only)

​
Authentication

Requires a valid user session. Admin role required for creating standard channels.

​
Request Body

​
type
string
Channel type: dm, group, or standard. Only admins can create standard channels.
​
name
string
required
Channel name (can be empty for DM channels)
​
description
string
Channel description
​
is_private
boolean
Whether the channel is private (for group channels)
​
user_ids
array
Array of user IDs to invite to the channel
​
group_ids
array
Array of group IDs to grant access to the channel
​
access_grants
array
Access control grants for the channel
​
data
object
Additional channel data
​
meta
object
Channel metadata

​
Response

Returns the created channel object.
​
id
string
required
Unique channel identifier
​
user_id
string
required
ID of the user who created the channel
​
type
string
Channel type
​
name
string
required
Channel name
​
description
string
Channel description
​
is_private
boolean
Whether the channel is private
​
access_grants
array
Access control grants
​
created_at
integer
required
Creation timestamp (epoch time in nanoseconds)
​
updated_at
integer
required
Last update timestamp (epoch time in nanoseconds)
curl -X POST "https://your-domain.com/api/channels/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "name": "announcements",
    "description": "Official announcements",
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      },
      {
        "principal_type": "role",
        "principal_id": "admin",
        "permission": "write"
      }
    ]
  }'

{
  "id": "ch_abc123",
  "user_id": "user_123",
  "type": "standard",
  "name": "announcements",
  "description": "Official announcements",
  "is_private": false,
  "data": null,
  "meta": null,
  "access_grants": [
    {
      "principal_type": "user",
      "principal_id": "*",
      "permission": "read"
    },
    {
      "principal_type": "role",
      "principal_id": "admin",
      "permission": "write"
    }
  ],
  "created_at": 1709567890123456789,
  "updated_at": 1709567890123456789,
  "updated_by": null,
  "archived_at": null,
  "archived_by": null,
  "deleted_at": null,
  "deleted_by": null
}

​
Notes

  • For DM channels, if a channel already exists between the specified users, the existing channel is returned instead of creating a duplicate
  • The creator is automatically added as a member of the channel with manager role
  • Only admins can create standard type channels
  • Members are automatically added to the channel’s socket room for real-time updates