Documentation Menu

Channel management

Create a channel

POST /workspaces/{wid}/channels/create

Requires authentication.

Create a new channel in the workspace. Channel names must be unique within the workspace and contain only lowercase letters, numbers, and hyphens. The creator is automatically added as a member with admin role.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "name": "general",
  "description": "string",
  "type": "public"
}

Responses

200 Channel created

{
  "channel": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "name": "general",
    "description": "string",
    "type": "public",
    "is_default": true,
    "dm_participant_hash": "hash_abc123",
    "archived_at": "2025-01-15T09:30:00Z",
    "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

List channels in workspace

POST /workspaces/{wid}/channels/list

Requires authentication.

List all channels in the workspace that the current user has access to. Includes the user's membership status and unread counts for each channel. Private channels are only listed if the user is a member.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 List of channels

{
  "channels": [
    {
      "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "name": "general",
      "description": "string",
      "type": "public",
      "is_default": true,
      "dm_participant_hash": "hash_abc123",
      "archived_at": "2025-01-15T09:30:00Z",
      "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T09:30:00Z",
      "channel_role": "admin",
      "last_read_message_id": "01JQ3KMR5KVDW2TG9NHP0XEJBL",
      "unread_count": 12,
      "notification_count": 3,
      "is_starred": true,
      "dm_participants": [
        {
          "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
          "email": "alice@example.com",
          "display_name": "Alice Chen",
          "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
          "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
          "channel_role": "admin"
        }
      ]
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Create or get DM channel

POST /workspaces/{wid}/channels/dm

Requires authentication.

Create a direct message channel with one or more users. If a DM already exists between the same set of users, returns the existing channel. For two users, creates a 1:1 DM; for more, creates a group DM.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_ids": [
    "string"
  ]
}

Responses

200 DM channel

{
  "channel": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "name": "general",
    "description": "string",
    "type": "public",
    "is_default": true,
    "dm_participant_hash": "hash_abc123",
    "archived_at": "2025-01-15T09:30:00Z",
    "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Update channel

POST /channels/{id}/update

Requires authentication.

Update channel properties such as name, description, or visibility (public/private). Requires channel admin role or workspace admin/owner role.

Parameters

Name In Type Description
id path string Channel ID

Request body 

{
  "name": "general",
  "description": "string",
  "type": "public"
}

Responses

200 Channel updated

{
  "channel": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "name": "general",
    "description": "string",
    "type": "public",
    "is_default": true,
    "dm_participant_hash": "hash_abc123",
    "archived_at": "2025-01-15T09:30:00Z",
    "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Convert group DM to channel

POST /channels/{id}/convert

Requires authentication.

Convert a group DM into a named public or private channel. Requires the caller to be a member of the group DM. All existing members and message history are preserved.

Parameters

Name In Type Description
id path string Channel ID

Request body 

{
  "name": "general",
  "description": "string",
  "type": "public"
}

Responses

200 Channel converted

{
  "channel": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "name": "general",
    "description": "string",
    "type": "public",
    "is_default": true,
    "dm_participant_hash": "hash_abc123",
    "archived_at": "2025-01-15T09:30:00Z",
    "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

Archive channel

POST /channels/{id}/archive

Requires authentication.

Archive a channel, preventing new messages from being sent. Archived channels remain visible and searchable but are moved to an archived section. Requires channel admin or workspace admin/owner role.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Channel archived

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Add member to channel

POST /channels/{id}/members/add

Requires authentication.

Add a workspace member to a channel. For public channels, any member can add others. For private channels, only channel members can add others.

Parameters

Name In Type Description
id path string Channel ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
  "role": "admin"
}

Responses

200 Member added

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

List channel members

POST /channels/{id}/members/list

Requires authentication.

List all members of a channel with their roles and join dates.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 List of members

{
  "members": [
    {
      "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "email": "alice@example.com",
      "display_name": "Alice Chen",
      "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
      "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
      "channel_role": "admin"
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Join a channel

POST /channels/{id}/join

Requires authentication.

Join a public channel. Private channels cannot be joined directly — a current member must add you using the add member endpoint.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Joined channel

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Leave a channel

POST /channels/{id}/leave

Requires authentication.

Leave a channel. You will no longer receive messages or notifications from this channel. The channel owner cannot leave without first transferring ownership.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Left channel

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Star a channel

POST /channels/{id}/star

Requires authentication.

Star a channel to pin it to the top of your sidebar. Starred channels appear in a separate section for quick access.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Channel starred

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Unstar a channel

DELETE /channels/{id}/star

Requires authentication.

Remove a channel from your starred list.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Channel unstarred

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Mark channel as read

POST /channels/{id}/mark-read

Requires authentication.

Mark a channel as read up to a specific message, or up to the latest message if no message ID is provided. Updates the unread count and clears notification badges for this channel.

Parameters

Name In Type Description
id path string Channel ID

Request body 

{
  "message_id": "01JQ3KMR5KVDW2TG9NHP0XEJBL"
}

Responses

200 Channel marked as read

{
  "last_read_message_id": "01JQ3KMR5KVDW2TG9NHP0XEJBL"
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Get channel notification preferences

GET /channels/{id}/notifications

Requires authentication.

Get the current user's notification preferences for a specific channel, such as whether to receive notifications for all messages, mentions only, or nothing.

Parameters

Name In Type Description
id path string Channel ID

Responses

200 Notification preferences

{
  "preferences": {
    "notify_level": "all",
    "email_enabled": true
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Update channel notification preferences

POST /channels/{id}/notifications

Requires authentication.

Set notification preferences for a specific channel. Overrides the workspace-level notification defaults for this channel only.

Parameters

Name In Type Description
id path string Channel ID

Request body 

{
  "notify_level": "all",
  "email_enabled": true
}

Responses

200 Preferences updated

{
  "preferences": {
    "notify_level": "all",
    "email_enabled": true
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Mark all channels as read

POST /workspaces/{wid}/channels/mark-all-read

Requires authentication.

Mark all channels in the workspace as read. Clears all unread counts and notification badges across every channel the user is a member of.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 All channels marked as read

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}