Get subscribed streams

GET https://macro1-2023.zulip.aalto.fi/api/v1/users/me/subscriptions

Get all streams that the user is subscribed to.

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://macro1-2023.zulip.aalto.fi/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

curl -sSX GET -G https://macro1-2023.zulip.aalto.fi/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.

  Changes: Removed email_address field from the dictionary in Zulip 8.0 (feature level 226).

  Changes: Removed role field from the dictionary in Zulip 6.0 (feature level 133).

  • 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.

  • 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.0, 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 meaning.

    Changes: Deprecated in Zulip 2.1.0. 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). Clients should 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.

  • 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 (feature level 1), 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.

    Is null for streams with no message history.

  • stream_weekly_traffic: integer | null

    The average number of messages sent to the stream per week, as estimated based on recent weeks, rounded to the nearest integer.

    If null, the stream was recently created and there is insufficient data to estimate the average traffic.

  • can_remove_subscribers_group: integer

    ID of the user group whose members are allowed to unsubscribe others from the stream.

    Changes: Before Zulip 8.0 (feature level 197), the can_remove_subscribers_group setting was named can_remove_subscribers_group_id.

    New in Zulip 6.0 (feature level 142).

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "subscriptions": [
        {
            "audible_notifications": true,
            "color": "#e79ab5",
            "description": "A Scandinavian country",
            "desktop_notifications": true,
            "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,
            "invite_only": false,
            "is_muted": false,
            "name": "Scotland",
            "pin_to_top": false,
            "push_notifications": false,
            "stream_id": 3,
            "subscribers": [
                7,
                11,
                12,
                14
            ]
        }
    ]
}