List Channels

Get all channels accessible to the current user

GET /api/channels

cURL

curl -X GET "https://your-domain.com/api/channels" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

200 OK

[
  {
    "id": "ch_abc123",
    "user_id": "user_123",
    "type": "standard",
    "name": "general",
    "description": "General discussion",
    "is_private": false,
    "data": {},
    "meta": {},
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      }
    ],
    "last_message_at": 1709567890123456789,
    "unread_count": 3,
    "created_at": 1709500000000000000,
    "updated_at": 1709567890123456789,
    "updated_by": "user_456"
  },
  {
    "id": "ch_dm789",
    "user_id": "user_123",
    "type": "dm",
    "name": "",
    "description": null,
    "is_private": null,
    "data": {},
    "meta": {},
    "access_grants": [],
    "user_ids": ["user_123", "user_456"],
    "users": [
      {
        "id": "user_123",
        "name": "Alice",
        "is_active": true
      },
      {
        "id": "user_456",
        "name": "Bob",
        "is_active": true
      }
    ],
    "last_message_at": 1709567890123456789,
    "unread_count": 0,
    "created_at": 1709500000000000000,
    "updated_at": 1709567890123456789
  }
]

Retrieves a list of all channels that the authenticated user has access to, including DM channels, group channels, and standard channels.

Authentication

Requires a valid user session. Channels must be enabled in the system configuration.

Response

Returns an array of channel objects with metadata.

channels · array

Array of channel objects

Show Channel Object

id · string · required

Unique channel identifier

user_id · string · required

ID of the user who created the channel

type · string

Channel type: standard, group, or dm

name · string · required

Channel name (empty for DM channels)

description · string

Channel description

is_private · boolean

Whether the channel is private (for group channels)

data · object

Additional channel data

meta · object

Channel metadata

access_grants · array

Access control grants for the channel

user_ids · array

Array of user IDs (for DM channels only)

users · array

Array of user objects with status (for DM channels only)

last_message_at · integer

Timestamp of the last message (epoch time in nanoseconds)

unread_count · integer

Number of unread messages for the current user

created_at · integer · required

Timestamp when the channel was created (epoch time in nanoseconds)

updated_at · integer · required

Timestamp when the channel was last updated (epoch time in nanoseconds)

updated_by · string

ID of the user who last updated the channel

cURL

curl -X GET "https://your-domain.com/api/channels" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

200 OK

[
  {
    "id": "ch_abc123",
    "user_id": "user_123",
    "type": "standard",
    "name": "general",
    "description": "General discussion",
    "is_private": false,
    "data": {},
    "meta": {},
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "*",
        "permission": "read"
      }
    ],
    "last_message_at": 1709567890123456789,
    "unread_count": 3,
    "created_at": 1709500000000000000,
    "updated_at": 1709567890123456789,
    "updated_by": "user_456"
  },
  {
    "id": "ch_dm789",
    "user_id": "user_123",
    "type": "dm",
    "name": "",
    "description": null,
    "is_private": null,
    "data": {},
    "meta": {},
    "access_grants": [],
    "user_ids": ["user_123", "user_456"],
    "users": [
      {
        "id": "user_123",
        "name": "Alice",
        "is_active": true
      },
      {
        "id": "user_456",
        "name": "Bob",
        "is_active": true
      }
    ],
    "last_message_at": 1709567890123456789,
    "unread_count": 0,
    "created_at": 1709500000000000000,
    "updated_at": 1709567890123456789
  }
]