Get subscribed streams

Get all streams that the user is subscribed to.

GET https://zulip.dioco.io/api/v1/users/me/subscriptions

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Get all streams that the user is subscribed to
result = client.list_subscriptions()
print(result)

More examples and documentation can be found here.

const Zulip = require('zulip-js');

// Pass the path to your zuliprc file here.
const config = { zuliprc: 'zuliprc' };

Zulip(config).then(async (client) => {
    // Get all streams that the user is subscribed to
    return await client.streams.subscriptions.retrieve();
}).then(console.log).catch(console.err);

curl -sSX GET -G https://zulip.dioco.io/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

You may pass the include_subscribers query parameter as follows:

curl -sSX GET -G https://zulip.dioco.io/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'include_subscribers=true'

Parameters

include_subscribers optional

Example: True

Whether each returned stream object should include a subscribers field containing a list of the user IDs of its subscribers.

(This may be significantly slower in organizations with thousands of users subscribed to many streams.)

Changes: New in Zulip 2.1.0.

Defaults to false.


Response

Return values

  • subscriptions: A list of dictionaries where each dictionary contains information about one of the subscribed streams.

    • stream_id: The unique ID of a stream.

    • name: The name of a stream.

    • description: The short description of a stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description.

    • rendered_description: A short description of a stream rendered as HTML, intended to be used when displaying the stream description in a UI.

      One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message.

    • invite_only: Specifies whether the stream is private or not. Only people who have been invited can access a private stream.

    • subscribers: A list of user IDs of users who are also subscribed to a given stream. Included only if include_subscribers is true.

    • desktop_notifications: A boolean specifying whether desktop notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this stream.

    • email_notifications: A boolean specifying whether email notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this stream.

    • wildcard_mentions_notify: A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this stream.

      A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this stream.

    • push_notifications: A boolean specifying whether push notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this stream.

    • audible_notifications: A boolean specifying whether audible notifications are enabled for the given stream.

      A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this stream.

    • pin_to_top: A boolean specifying whether the given stream has been pinned to the top.

    • email_address: Email address of the given stream, used for sending emails to the stream.

    • is_muted: Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in All messages view (previously known as Home view).

      Changes: Prior to Zulip 2.1, this feature was represented by the more confusingly named in_home_view (with the opposite value, in_home_view=!is_muted).

    • in_home_view: Legacy property for if the given stream is muted, with inverted meeting.

      Deprecated; clients should use is_muted where available.

    • is_announcement_only: Whether only organization administrators can post to the stream.

      Changes: Deprecated in Zulip 3.0 (feature level 1), use stream_post_policy instead.

    • is_web_public: Whether the stream has been configured to allow unauthenticated access to its message history from the web.

    • color: The user's personal color for the stream.

    • stream_post_policy: Policy for which users can post messages to the stream.

      • 1 => Any user can post.
      • 2 => Only administrators can post.
      • 3 => Only new members can post.

      Changes: New in Zulip 3.0, replacing the previous is_announcement_only boolean.

    • message_retention_days: Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. There are two special values:

      • null, the default, means the stream will inherit the organization level setting.
      • -1 encodes retaining messages in this stream forever.

      Changes: New in Zulip 3.0 (feature level 17).

    • history_public_to_subscribers: Whether the history of the stream is public to its subscribers.

      Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future.

    • first_message_id: The id of the first message in the stream.

      Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed.

      Null is used for streams with no message history.

    • stream_weekly_traffic: The average number of messages sent to the stream in recent weeks, rounded to the nearest integer.

      Null means the stream was recently created and there is insufficient data to estimate the average traffic.

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "subscriptions": [
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "description": "A Scandinavian country",
            "desktop_notifications": true,
            "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981",
            "invite_only": false,
            "is_muted": false,
            "name": "Denmark",
            "pin_to_top": false,
            "push_notifications": false,
            "stream_id": 1,
            "subscribers": [
                7,
                10,
                11,
                12,
                14
            ]
        },
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "description": "Located in the United Kingdom",
            "desktop_notifications": true,
            "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981",
            "invite_only": false,
            "is_muted": false,
            "name": "Scotland",
            "pin_to_top": false,
            "push_notifications": false,
            "stream_id": 3,
            "subscribers": [
                7,
                11,
                12,
                14
            ]
        }
    ]
}