Returning.AIDevelopers
v1

API reference / Channels

.md

List integration channels

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

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/channels
Permission
None
Retries
Read-only; exact retries are safe

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.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
NoneAny Community API key for this community works

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#

Authorization#stringOPTIONAL
Community API key. No specific permission is needed.

RuleBearer <API_KEY>

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.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Get channels list successfully"

data#object[]ALWAYS
Every channel in your community, in the community's channel order. Direct-message and deleted channels are left out.

Eg[ ... ]

_id#stringALWAYS
The channel ID. Send it as channel_id to Get Messages and as channelId to Send Message.

Eg"66f000000000000000000a11"

topic#stringALWAYS
The channel's name, as shown in the community.

Eg"general"

channelType#stringALWAYS
The channel type, such as open.

Eg"open"

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

401Fix the request
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 backoff01

500Retry with backoff
The read failed, or the key could not be checked (Authentication failed). Retry the same request with exponential backoff.
{
  "status": "error",
  "message": "Invalid API key"
}

Next step#

Get messagesGET/v1/messagesRead the latest messages in a channel with its _id as channel_id.