Create Channel

Create a new channel

POST /api/channels/create

Create Standard Channel

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"
      }
    ]
  }'

200 OK

{
  "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

Show Access Grant Object

principal_type · string · required

Type of principal: user, group, or role

principal_id · string · required

ID of the principal, or * for public access

permission · string · required

Permission level: read or write

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)

Create Standard Channel

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"
      }
    ]
  }'

200 OK

{
  "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