Get all streams

Get all streams that the user has access to.

GET https://zulip.dioco.io/api/v1/streams

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)

#!/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)

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

curl -sSX GET -G https://zulip.dioco.io/api/v1/streams \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'include_public=false'

Parameters

Note: The following parameters are all URL query parameters.

Response

Return values

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

  • stream_id: The unique ID of the stream.

  • name: The name of the stream.

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

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

  • rendered_description: 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: Whether the stream has been configured to allow unauthenticated access to its message history from the web.

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

  • is_announcement_only: Whether the given stream is announcement only or not.

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

  • is_default: Whether the given stream is a default stream. Only returned if the include_default parameter is true.

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "streams": [
        {
            "description": "A Scandinavian country",
            "invite_only": false,
            "name": "Denmark",
            "stream_id": 1
        },
        {
            "description": "Yet another Italian city",
            "invite_only": false,
            "name": "Rome",
            "stream_id": 2
        },
        {
            "description": "Located in the United Kingdom",
            "invite_only": false,
            "name": "Scotland",
            "stream_id": 3
        },
        {
            "description": "A northeastern Italian city",
            "invite_only": false,
            "name": "Venice",
            "stream_id": 4
        },
        {
            "description": "A city in Italy",
            "invite_only": false,
            "name": "Verona",
            "stream_id": 5
        },
        {
            "description": "New stream for testing",
            "invite_only": false,
            "name": "new stream",
            "stream_id": 6
        }
    ]
}

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"
}