Get a channel by ID

GET https://developing-today.zulipchat.com/api/v1/streams/{stream_id}

Fetch details for the channel with the ID stream_id.

Changes: New in Zulip 6.0 (feature level 132).

Usage examples

curl -sSX GET -G https://developing-today.zulipchat.com/api/v1/streams/1 \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

Response

Return values

• stream: object

  Object containing basic details about the channel.

  • stream_id: integer

    The unique ID of the channel.

  • name: string

    The name of the channel.

  • is_archived: boolean

    A boolean indicating whether the channel is archived.

    Changes: New in Zulip 10.0 (feature level 315). Previously, this endpoint never returned archived channels.

  • description: string

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

  • date_created: integer

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

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

  • creator_id: integer | null

    The ID of the user who created this channel.

    A null value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or management command.

    Changes: New in Zulip 9.0 (feature level 254).

  • invite_only: boolean

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

  • rendered_description: string

    The short description of the channel rendered as HTML, intended to be used when displaying the channel 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 channel 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 channel.

    • 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 channel will be stored before being automatically deleted by the message retention policy. There are two special values:

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

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

  • history_public_to_subscribers: boolean

    Whether the history of the channel is public to its subscribers.

    Currently always true for public channels (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 channel.

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

    Is null for channels with no message history.

    Changes: New in Zulip 2.1.0.

  • is_announcement_only: boolean

    Whether the given channel 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 channel.

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

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",
    "stream": {
        "can_remove_subscribers_group": 2,
        "creator_id": null,
        "date_created": 1691057093,
        "description": "A Scandinavian country",
        "first_message_id": 1,
        "history_public_to_subscribers": true,
        "invite_only": false,
        "is_announcement_only": false,
        "is_archived": false,
        "is_web_public": false,
        "message_retention_days": null,
        "name": "Denmark",
        "rendered_description": "<p>A Scandinavian country</p>",
        "stream_id": 7,
        "stream_post_policy": 1,
        "stream_weekly_traffic": null
    }
}

An example JSON response for when the channel ID is not valid:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid channel ID",
    "result": "error"
}