---
title: "Subscriptions"
slug: "subscriptions-api"
status: "update"
updated: 2026-09-15T13:53:15Z
published: 2026-09-15T13:53:19Z
canonical: "developer.rocket.chat/subscriptions-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

With the **Subscriptions API**, you can:

- Get subscription and notification details for rooms.
- Mark a channel as read or unread.

## The subscription object

A subscription is one user's view of one room: what the room is called for them, whether it is open, and how much of it they have read. A trimmed example from [Get All Subscriptions](https://developer.rocket.chat/apidocs/get-all-subscriptions):

```json
{
  "update": [
    {
      "_id": "5ALsG3QhpJfdMpyc8",
      "rid": "GENERAL",
      "name": "general",
      "t": "c",
      "u": { "_id": "EoyAmF4mxx5HxJHJB", "username": "rocket.cat" },
      "open": true,
      "alert": true,
      "unread": 1,
      "userMentions": 1,
      "groupMentions": 0,
      "ts": "2017-11-25T15:08:17.249Z"
    }
  ],
  "remove": [],
  "success": true
}
```

Fields you use most often:

- `rid`: The ID of the room this subscription belongs to. `_id` identifies the subscription itself.
- `unread`, `userMentions`, `groupMentions`: Unread counters for this user in this room.
- `alert` and `open`: Whether the room should be highlighted and whether it is shown in the user's room list.
- `t`: The room type — `c` channel, `p` private group, `d` direct message, `l` livechat.

## Common workflows

**Build an unread indicator**

1. [Get all subscriptions](https://developer.rocket.chat/apidocs/get-all-subscriptions) for the authenticated user. Pass `updatedSince` on later calls to fetch only what changed.
2. Sum the `unread` and mention counters per room, or [get one room's subscription](https://developer.rocket.chat/apidocs/get-subscription-room) by its `roomId`.
3. [Mark the room as read](https://developer.rocket.chat/apidocs/mark-channel-as-read) when the user opens it, or [mark it as unread](https://developer.rocket.chat/apidocs/mark-channel-as-unread) so they come back to it.

## Conventions

- Subscriptions always belong to the authenticated user — you read and update your own read state, not other users'.
- Endpoints reference rooms by `roomId` (the subscription's `rid`).
- The full field list is documented in the [Subscription schema definition](https://developer.rocket.chat/apidocs/subscription-schema).