Skip to main content

Channels API

The Channels API provides server-side read access to channel metadata and storage entries. These endpoints are authenticated with the same API keys used for HTTP message publishing.

Authentication​

All requests must include an Authorization header with a Bearer token set to one of your installation's API keys, available at HttpApiSecretKey1ConsoleUrl or HttpApiSecretKey2ConsoleUrl.

Your base URL is available in your installation's HttpApiUrl stack output.

Authorization: Bearer YOUR_API_KEY

GET /channels/{name}​

Retrieve metadata for a channel, including the current subscription count.

Example​

Request​

curl "https://r6zcm2.lambda-url.us-east-1.on.aws/channels/my-channel" \
  -H 'Authorization: Bearer JAnzQFqRXsBgV0kKvd2DYhJMk77IhL8j9J2sLi5b'

Response​

{
  "name": "my-channel",
  "subscriptionsCount": 12
}

For presence channels, the response includes a deduplicated members array:

{
  "name": "presence.chat",
  "subscriptionsCount": 4,
  "members": [
    { "uid": "Jim", "umd": null },
    { "uid": "Dwight", "umd": { "status": "available" } },
    { "uid": "Pam", "umd": null }
  ]
}
note

subscriptionsCount reflects the total number of subscriptions on the channel, while members is deduplicated by uid. If a user is connected from multiple devices, they appear once in members but count as multiple subscriptions.

If the channel has no active subscriptions or has never been used, subscriptionsCount is 0. For presence channels with no members, members is an empty array.

GET /channels/{name}/storage​

List storage entries for a channel. Returns a paginated list of all storage entries, or specific entries when keys are requested.

Query parameters​

after​

String (optional) - For pagination, the storage key to start after. Returns entries with keys that sort after this value.

keys​

String (optional) - Comma-separated list of specific storage keys to retrieve. Maximum of 100 keys per request.

Example​

Request​

List all storage entries for a channel:

curl "https://r6zcm2.lambda-url.us-east-1.on.aws/channels/my-channel/storage" \
  -H 'Authorization: Bearer JAnzQFqRXsBgV0kKvd2DYhJMk77IhL8j9J2sLi5b'

Fetch specific keys:

curl "https://r6zcm2.lambda-url.us-east-1.on.aws/channels/my-channel/storage?keys=settings,status" \
  -H 'Authorization: Bearer JAnzQFqRXsBgV0kKvd2DYhJMk77IhL8j9J2sLi5b'

Response​

{
  "items": [
    {
      "key": "settings",
      "data": { "theme": "dark" },
      "meta": { "uid": "12345", "umd": null }
    },
    {
      "key": "status",
      "data": "online",
      "meta": { "uid": "12345", "umd": null }
    }
  ]
}

If there are no storage entries, items is an empty array.