Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Drafts

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Update a stream

Configure the stream with the ID stream_id. This endpoint supports an organization administrator editing any property of a stream, including:

PATCH https://zulip.schiffrin-zulip.cloud.edu.au/api/v1/streams/{stream_id}

Usage examples

  • Python
  • curl

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Update the stream by a given ID
request = {
    "stream_id": stream_id,
    "stream_post_policy": 2,
    "is_private": True,
}

result = client.update_stream(request)
print(result)


curl -sSX PATCH https://zulip.schiffrin-zulip.cloud.edu.au/api/v1/streams/1 \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'description=Discuss Italian history and travel destinations.' \
    --data-urlencode new_name=Italy \
    --data-urlencode is_private=true

Parameters

stream_id integer required in path

Example: 1

The ID of the stream to access.

description string optional

Example: "Discuss Italian history and travel destinations."

The new description for the stream. Limited Zulip markdown is allowed in this field.

Changes: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64).

new_name string optional

Example: "Italy"

The new name for the stream.

Changes: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64).

is_private boolean optional

Example: true

Change whether the stream is a private stream.

is_web_public boolean optional

Example: true

Change whether the stream is a web-public stream.

Note that creating web-public streams requires the WEB_PUBLIC_STREAMS_ENABLED server setting to be enabled on the Zulip server in question, the organization to have enabled the enable_spectator_access realm setting, and the current use to have permission under the organization's create_web_public_stream_policy realm setting.

Changes: New in Zulip 5.0 (feature level 98).

stream_post_policy integer optional

Example: 2

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.

Defaults to 1.

history_public_to_subscribers boolean optional

Example: false

Whether the stream's message history should be available to newly subscribed members, or users can only access messages they actually received while subscribed to the stream.

Corresponds to the shared history option in documentation.

message_retention_days string | integer optional

Example: "20"

Number of days that messages sent to this stream will be stored before being automatically deleted by the message retention policy. Two special string format values are supported:

  • "realm_default" => Return to the organization-level setting.
  • "unlimited" => Retain messages forever.

Changes: Prior to Zulip 5.0 (feature level 91), retaining messages forever was encoded using "forever" instead of "unlimited".

New in Zulip 3.0 (feature level 17).

is_announcement_only boolean optional Deprecated

Example: true

Whether the stream is limited to announcements.

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

Response

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success"
}

An example JSON response for when the supplied stream does not exist:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid stream id",
    "result": "error"
}