Get all streams

GET https://testrealm.zulip.cs.aalto.fi/api/v1/streams

Get all streams that the user has access 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 has access to
result = client.get_streams()
# You may pass in one or more of the query parameters mentioned above
# as keyword arguments, like so:
result = client.get_streams(include_public=False)
print(result)

More examples and documentation can be found here.

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 has access to
    console.log(await client.streams.retrieve());
})();

curl -sSX GET -G https://testrealm.zulip.cs.aalto.fi/api/v1/streams \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

You may pass in one or more of the parameters mentioned below as URL query parameters, like so:

curl -sSX GET -G https://testrealm.zulip.cs.aalto.fi/api/v1/streams \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode include_public=false

Parameters

include_public boolean optional

Example: false

Include all public streams.

Defaults to true.


include_web_public boolean optional

Example: true

Include all web-public streams.

Defaults to false.


include_subscribed boolean optional

Example: false

Include all streams that the user is subscribed to.

Defaults to true.


include_all_active boolean optional

Example: true

Include all active streams. The user must have administrative privileges to use this parameter.

Defaults to false.


include_default boolean optional

Example: true

Include all default streams for the user's realm.

Defaults to false.


include_owner_subscribed boolean optional

Example: true

If the user is a bot, include all streams that the bot's owner is subscribed to.

Defaults to false.


Response

Return values

  • streams: (object)[]

    A list of stream objects with details on the requested streams.

    • stream_id: integer

      The unique ID of the stream.

    • name: string

      The name of the stream.

    • description: string

      The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's 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.

    • rendered_description: string

      The short 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.

    • is_web_public: boolean

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

      Changes: New in Zulip 2.1.0.

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

      Changes: New in Zulip 2.1.0.

    • is_announcement_only: boolean

      Whether the given stream is announcement only or not.

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

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

    • 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, no information is provided on the average traffic. This can be because the stream was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event.

      Changes: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects.

    • is_default: boolean

      Only present when include_default parameter is true.

      Whether the given stream is a default stream.

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",
    "streams": [
        {
            "can_remove_subscribers_group": 10,
            "date_created": 1691057093,
            "description": "A private stream",
            "first_message_id": 18,
            "history_public_to_subscribers": false,
            "invite_only": true,
            "is_announcement_only": false,
            "is_default": false,
            "is_web_public": false,
            "message_retention_days": null,
            "name": "management",
            "rendered_description": "<p>A private stream</p>",
            "stream_id": 2,
            "stream_post_policy": 1,
            "stream_weekly_traffic": null
        },
        {
            "can_remove_subscribers_group": 9,
            "date_created": 1691057093,
            "description": "A default public stream",
            "first_message_id": 21,
            "history_public_to_subscribers": true,
            "invite_only": false,
            "is_announcement_only": false,
            "is_default": true,
            "is_web_public": false,
            "message_retention_days": null,
            "name": "welcome",
            "rendered_description": "<p>A default public stream</p>",
            "stream_id": 1,
            "stream_post_policy": 1,
            "stream_weekly_traffic": null
        }
    ]
}

An example JSON response for when the user is not authorized to use the include_all_active parameter (i.e. because they are not an organization administrator):

{
    "code": "BAD_REQUEST",
    "msg": "User not authorized for this query",
    "result": "error"
}