Get subscribed streams

Get all streams that the user is subscribed to.

GET https://dev.zulip.pr.business/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.get_subscriptions()
print(result)

const zulipInit = require("zulip-js");

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

(async () => {
    const client = await zulipInit(config);

    // Get all streams that the user is subscribed to
    console.log(await client.streams.subscriptions.retrieve());
})();

curl -sSX GET -G https://dev.zulip.pr.business/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

curl -sSX GET -G https://dev.zulip.pr.business/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode include_subscribers=true

Parameters

Response

Return values

• subscriptions: (object)[]

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

  • stream_id: integer

    The unique ID of a stream.

  • name: string

    The name of a stream.

  • description: string

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

    See also rendered_description.

  • rendered_description: string

    The description of the 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.

    See also description.

  • date_created: integer

    The UNIX timestamp for when the stream was created, in UTC seconds.

    Changes: New in Zulip 4.0 (feature level 30).

  • invite_only: boolean

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

  • subscribers: (integer)[]

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

  • desktop_notifications: boolean | null

    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: boolean | null

    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: boolean | null

    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: boolean | null

    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: boolean | null

    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: boolean

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

  • email_address: string

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

  • is_muted: boolean

    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: boolean

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

    Deprecated; clients should use is_muted where available.

  • is_announcement_only: boolean

    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: boolean

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

  • role: integer

    The user's role within the stream (distinct from the user's organization-level role). Valid values are:

    • 20 => Stream administrator.
    • 50 => Subscriber.

    Changes: New in Zulip 4.0 (feature level 31).

  • color: string

    The user's personal color for the stream.

  • stream_post_policy: integer

    Policy for which users can post messages to the stream.

    • 1 => Any user can post.
    • 2 => Only administrators can post.
    • 3 => Only full members can post.
    • 4 => Only moderators can post.

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

  • message_retention_days: integer | null

    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: boolean

    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: integer | null

    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: integer | null

    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,
            "role": 20,
            "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,
            "role": 50,
            "stream_id": 3,
            "subscribers": [
                7,
                11,
                12,
                14
            ]
        }
    ]
}