Skip to content
The Desk

List channels

GET
/channels
curl --request GET \
  --url https://desk.example.com/api/v1/channels \
  --header 'Authorization: Bearer <token>'

Required scope: channels:read

Lists the channels the token’s subject may view within its acting team, ordered by name. A bot sees only the channels it belongs to; a personal access token sees what the person sees in the app — every public channel in the team plus the private ones they belong to.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The channels the subject may view.

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string format: uuid
name
required
string
slug
required
string
visibility
required

Whether the channel is open to the whole team or invite-only.

string
Allowed values: public private
topic
required
string | null
is_general
required

Whether this is the workspace’s default channel.

boolean
is_archived
required
boolean
is_direct
required

Whether this is a direct-message conversation.

boolean
created_at
required
string | null format: date-time
Example
{
  "data": [
    {
      "visibility": "public"
    }
  ]
}

401

Section titled “401”

The token is missing, malformed, or revoked.

Media typeapplication/json

The shape every error response carries.

object
message
required
string
Examplegenerated
{
  "message": "example"
}

403

Section titled “403”

The token lacks the scope this operation requires, or its subject may see the resource but not perform this action on it.

Media typeapplication/json

The shape every error response carries.

object
message
required
string
Examplegenerated
{
  "message": "example"
}

404

Section titled “404”

The resource does not exist, is outside the token’s workspace, or the integrations platform is disabled. A channel the subject cannot see is reported here rather than as a 403, so the API never leaks its existence.

Media typeapplication/json

The shape every error response carries.

object
message
required
string
Examplegenerated
{
  "message": "example"
}

429

Section titled “429”

The per-token rate limit (INTEGRATIONS_API_RATE_LIMIT requests per minute) was exceeded. Retry after the Retry-After header.

Media typeapplication/json

The shape every error response carries.

object
message
required
string
Examplegenerated
{
  "message": "example"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.