# List integration channels

List the chat channels in the community that owns your API key, with each channel's ID, name and type.

- Endpoint: `GET https://api.returning.ai/v1/channels`
- Section: Community / Channels
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `None` (Any Community API key for this community works)
- Retries: Read-only; exact retries are safe
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/channels/list-integration-channels

## When to use this

- You need a channel ID before you read, send or reply to messages.
- You want to show your team which channels exist, in the order the community shows them.
- An admin added a channel and you want its ID.

**Instead:** Use [Get Messages](https://docs.returning.ai/api-reference/messaging/get-messages.md) instead when you already have the channel ID and want its latest messages.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `None`

Send a Community API key as `Authorization: Bearer <API_KEY>`, and keep it on your server. No specific permission is needed. The key decides the community, so you only see that community's channels and never send a community ID.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | No | Community API key. No specific permission is needed. (`Bearer <API_KEY>`) |

### Example request

```bash
curl --request GET \
  --url https://api.returning.ai/v1/channels \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

A `200` returns every channel in `data`, in the order the community lists them. There is no paging. Each channel has only `_id`, `topic` and `channelType`; member lists and channel settings aren't included.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object[]` | always | Every channel in your community, in the community's channel order. Direct-message and deleted channels are left out. |
| `data._id` | `string` | always | The channel ID. Send it as `channel_id` to Get Messages and as `channelId` to Send Message. |
| `data.topic` | `string` | always | The channel's name, as shown in the community. |
| `data.channelType` | `string` | always | The channel type, such as `open`. |

### Example response (200)

```json
{
  "status": "success",
  "message": "Get channels list successfully",
  "data": [
    {
      "_id": "66f000000000000000000a11",
      "topic": "general",
      "channelType": "open"
    },
    {
      "_id": "66f000000000000000000a12",
      "topic": "trading-ideas",
      "channelType": "open"
    }
  ]
}
```

## Errors

Errors on this endpoint have no machine-readable code. Branch on the HTTP status, and read `message` for the reason.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 401 | - | `message` says which: `Invalid token` (no `Authorization` header), `Invalid API key` (unknown key) or `API key expired`. Send `Authorization: Bearer <API_KEY>` with a current key. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | The read failed, or the key could not be checked (`Authentication failed`). Retry the same request with exponential backoff. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error or a `500`. Use bounded exponential backoff. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get messages](https://docs.returning.ai/api-reference/messaging/get-messages.md): `GET /v1/messages`. Read the latest messages in a channel with its `_id` as `channel_id`.
- [Post to a channel with Send Message](https://docs.returning.ai/api-reference/messaging/send-message.md): `POST /v1/messages/send`.