Zulip channels API
The channels API from Zulip — 23 operation(s) for channels.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication channels API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: channels
paths:
/get_stream_id:
get:
operationId: get-stream-id
summary: Get channel ID
tags:
- channels
description: 'Get the unique ID of a given channel.
'
parameters:
- name: stream
in: query
description: 'The name of the channel to access.
'
schema:
type: string
example: Denmark
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
stream_id:
type: integer
description: 'The ID of the given channel.
'
example:
msg: ''
result: success
stream_id: 15
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Invalid channel name 'nonexistent'
result: error
description: 'An example JSON response for when the supplied channel does not exist:
'
/default_streams:
post:
operationId: add-default-stream
tags:
- channels
summary: Add a default channel
x-requires-administrator: true
description: 'Add a channel to the set of [default channels][default-channels]
for new users joining the organization.
[default-channels]: /help/set-default-channels-for-new-users
'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: 'The ID of the target channel.
'
type: integer
example: 10
required:
- stream_id
encoding:
stream_id:
contentType: application/json
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/InvalidChannelError'
- description: 'A typical failed JSON response for when an invalid channel ID is passed:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Private channels cannot be made default.
result: error
description: 'A typical failed JSON response for when a user tries to add a private channel
to the default channels set:
'
delete:
operationId: remove-default-stream
summary: Remove a default channel
tags:
- channels
description: 'Remove a channel from the set of [default channels][default-channels]
for new users joining the organization.
[default-channels]: /help/set-default-channels-for-new-users
'
x-requires-administrator: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: 'The ID of the target channel.
'
type: integer
example: 10
required:
- stream_id
encoding:
stream_id:
contentType: application/json
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/InvalidChannelError'
- description: 'A typical failed JSON response for when an invalid channel ID is passed:
'
/users/me/{stream_id}/topics:
get:
operationId: get-stream-topics
summary: Get topics in a channel
tags:
- channels
description: 'Get all topics the user has access to in a specific channel.
Note that for [private channels with
protected history](/help/channel-permissions#private-channels),
the user will only have access to topics of messages sent after they
[subscribed to](/api/subscribe) the channel. Similarly, a user''s
[bot](/help/bots-overview#bot-type) will only have access to messages
sent after the bot was subscribed to the channel, instead of when the
user subscribed.
**Changes**: Before Zulip 12.0 (feature level 480), this
endpoint was not supported for archived channels.
'
parameters:
- $ref: '#/components/parameters/ChannelIdInPath'
- name: allow_empty_topic_name
in: query
description: 'Whether the client supports processing the empty string as
a topic name in the returned data.
If `false`, the value of `realm_empty_topic_display_name`
found in the [`POST /register`](/api/register-queue) response is
returned replacing the empty string as the topic name.
**Changes**: New in Zulip 10.0 (feature level 334). Previously,
the empty string was not a valid topic.
'
schema:
type: boolean
default: false
example: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
topics:
type: array
description: 'An array of objects with information about user-accessible
topics in the specified channel, sorted by recency (i.e.,
the topic with the most recent message is ordered first).
'
items:
type: object
additionalProperties: false
properties:
max_id:
description: 'The message ID of the last message sent to this topic.
'
type: integer
name:
description: 'The name of the topic.
'
type: string
example:
msg: ''
result: success
topics:
- max_id: 26
name: Denmark3
- max_id: 23
name: Denmark1
- max_id: 6
name: Denmark2
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/InvalidChannelError'
- description: 'An example JSON response for when the user is attempting to fetch the topics
of a non-existing channel (or also a private channel they don''t have access to):
'
/users/me/subscriptions:
get:
operationId: get-subscriptions
summary: Get subscribed channels
tags:
- channels
description: 'Get all channels that the user is subscribed to.
'
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ''
- type: exclude
description: 'You may pass the `include_subscribers` query parameter as follows:
'
parameters:
enum:
- ''
parameters:
- $ref: '#/components/parameters/IncludeSubscribers'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- required:
- subscriptions
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
subscriptions:
type: array
description: 'A list of dictionaries where each dictionary contains
information about one of the subscribed channels.
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
Removed `role` field from the dictionary
in Zulip 6.0 (feature level 133).
'
items:
$ref: '#/components/schemas/Subscription'
example:
msg: ''
result: success
subscriptions:
- audible_notifications: true
color: '#e79ab5'
creator_id: null
description: A Scandinavian country
desktop_notifications: true
is_archived: false
is_muted: false
invite_only: false
name: Denmark
pin_to_top: false
push_notifications: false
stream_id: 1
subscribers:
- 7
- 10
- 11
- 12
- 14
- audible_notifications: true
color: '#e79ab5'
creator_id: 8
description: Located in the United Kingdom
desktop_notifications: true
is_archived: false
is_muted: false
invite_only: false
name: Scotland
pin_to_top: false
push_notifications: false
stream_id: 3
subscribers:
- 7
- 11
- 12
- 14
post:
operationId: subscribe
summary: Subscribe to a channel
tags:
- channels
description: 'Subscribe one or more users to one or more channels.
If any of the specified channels do not exist, they are automatically
created. The initial [channel settings](/api/update-stream) will be determined
by the optional parameters, like `invite_only`, detailed below.
Note that the ability to subscribe oneself and/or other users
to a specified channel depends on the [channel''s permissions
settings](/help/channel-permissions).
**Changes**: Before Zulip 10.0 (feature level 362),
subscriptions in archived channels could not be modified.
Before Zulip 10.0 (feature level 357), the
`can_subscribe_group` permission, which allows members of the
group to subscribe themselves to the channel, did not exist.
Before Zulip 10.0 (feature level 349), a user cannot subscribe
other users to a private channel without being subscribed
to that channel themselves. Now, If a user is part of
`can_add_subscribers_group`, they can subscribe themselves or other
users to a private channel without being subscribed to that channel.
Removed `stream_post_policy` and `is_announcement_only`
parameters in Zulip 10.0 (feature level 333), as permission to post
in the channel is now controlled by `can_send_message_group`.
Before Zulip 8.0 (feature level 208), if a user specified by the
[`principals`][principals-param] parameter was a deactivated user,
or did not exist, then an HTTP status code of 403 was returned with
`code: "UNAUTHORIZED_PRINCIPAL"` in the error response. As of this
feature level, an HTTP status code of 400 is returned with
`code: "BAD_REQUEST"` in the error response for these cases.
[principals-param]: /api/subscribe#parameter-principals
'
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- subscriptions
- type: include
description: 'To subscribe another user to a channel, you may pass in
the `principals` parameter, like so:
'
parameters:
enum:
- subscriptions
- principals
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subscriptions:
description: 'A list of dictionaries containing the key `name` and value
specifying the name of the channel to subscribe. If the channel does not
exist a new channel is created. The description of the channel created can
be specified by setting the dictionary key `description` with an
appropriate value.
'
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: 'The name of the channel.
Clients should use the `max_stream_name_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum channel name length.
'
description:
type: string
description: 'The [description](/help/change-the-channel-description)
to use for a new channel being created, in text/markdown format.
See the help center article on [message formatting](/help/format-your-message-using-markdown) for details on Zulip-flavored Markdown.
Clients should use the `max_stream_description_length` returned
by the [`POST /register`](/api/register-queue) endpoint to
determine the maximum channel description length.
'
required:
- name
example:
no-description:
value:
name: Verona
with-description:
value:
name: Verona
description: Italian city
example:
- name: Verona
description: Italian city
principals:
$ref: '#/components/schemas/Principals'
authorization_errors_fatal:
description: 'A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private channel) should be
considered fatal or not. When `true`, an authorization error is reported
as such. When set to `false`, the response will be a 200 and any channels
where the request encountered an authorization error will be listed
in the `unauthorized` key.
'
type: boolean
default: true
example: false
announce:
description: 'If one of the channels specified did not exist previously and is thus created
by this call, this determines whether [notification bot](/help/configure-automated-notices)
will send an announcement about the new channel''s creation.
'
type: boolean
default: false
example: true
invite_only:
description: 'As described above, this endpoint will create a new channel if passed
a channel name that doesn''t already exist. This parameters and the ones
that follow are used to request an initial configuration of a created
channel; they are ignored for channels that already exist.
This parameter determines whether any newly created channels will be
private channels.
'
type: boolean
default: false
example: true
is_web_public:
description: 'This parameter determines whether any newly created channels will be
web-public channels.
Note that creating web-public channels requires the
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
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
`can_create_web_public_channel_group` realm setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 98).
'
type: boolean
default: false
example: true
is_default_stream:
description: 'This parameter determines whether any newly created channels will be
added as [default channels][default-channels] for new users joining
the organization.
[default-channels]: /help/set-default-channels-for-new-users
**Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status
could only be changed using the [dedicated API endpoint](/api/add-default-stream).
'
type: boolean
default: false
example: true
history_public_to_subscribers:
$ref: '#/components/schemas/HistoryPublicToSubscribers'
message_retention_days:
$ref: '#/components/schemas/MessageRetentionDays'
topics_policy:
$ref: '#/components/schemas/TopicsPolicy'
can_add_subscribers_group:
$ref: '#/components/schemas/ChannelCanAddSubscribersGroup'
can_remove_subscribers_group:
$ref: '#/components/schemas/CanRemoveSubscribersGroup'
can_administer_channel_group:
$ref: '#/components/schemas/CanAdministerChannelGroup'
can_delete_any_message_group:
$ref: '#/components/schemas/CanDeleteAnyMessageGroup'
can_delete_own_message_group:
$ref: '#/components/schemas/CanDeleteOwnMessageGroup'
can_move_messages_out_of_channel_group:
$ref: '#/components/schemas/CanMoveMessagesOutOfChannelGroup'
can_move_messages_within_channel_group:
$ref: '#/components/schemas/CanMoveMessagesWithinChannelGroup'
can_send_message_group:
$ref: '#/components/schemas/CanSendMessageGroup'
can_subscribe_group:
$ref: '#/components/schemas/CanSubscribeGroup'
can_resolve_topics_group:
$ref: '#/components/schemas/CanResolveTopicsGroup'
can_create_topic_group:
$ref: '#/components/schemas/CanCreateTopicGroup'
folder_id:
description: 'This parameter adds the newly created channel to the specified
[channel folder](/help/channel-folders).
**Changes**: New in Zulip 11.0 (feature level 389).
'
type: integer
example: 1
send_new_subscription_messages:
$ref: '#/components/schemas/SendNewSubscriptionMessages'
required:
- subscriptions
encoding:
subscriptions:
contentType: application/json
principals:
contentType: application/json
authorization_errors_fatal:
contentType: application/json
announce:
contentType: application/json
invite_only:
contentType: application/json
is_web_public:
contentType: application/json
is_default_stream:
contentType: application/json
history_public_to_subscribers:
contentType: application/json
topics_policy:
contentType: application/json
can_add_subscribers_group:
contentType: application/json
can_remove_subscribers_group:
contentType: application/json
can_administer_channel_group:
contentType: application/json
can_delete_any_message_group:
contentType: application/json
can_delete_own_message_group:
contentType: application/json
can_move_messages_out_of_channel_group:
contentType: application/json
can_move_messages_within_channel_group:
contentType: application/json
can_send_message_group:
contentType: application/json
can_subscribe_group:
contentType: application/json
can_resolve_topics_group:
contentType: application/json
can_create_topic_group:
contentType: application/json
folder_id:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
subscribed:
type: object
description: 'A dictionary where the key is the ID of the user and the value
is a list of the names of the channels that user was subscribed
to as a result of the request.
**Changes**: Before Zulip 10.0 (feature level 289), the user
keys were Zulip API email addresses, not user ID.
'
additionalProperties:
description: '`{id}`: List of the names of the channels that were subscribed
to as a result of the query.
'
type: array
items:
type: string
already_subscribed:
type: object
description: 'A dictionary where the key is the ID of the user and the value
is a list of the names of the channels that where the user was
not added as a subscriber in this request, because they were
already a subscriber.
**Changes**: Before Zulip 10.0 (feature level 289), the user
keys were Zulip API email addresses, not user IDs.
'
additionalProperties:
description: '`{id}`: List of the names of the channels that the user is
already subscribed to.
'
type: array
items:
type: string
unauthorized:
type: array
items:
type: string
description: 'A list of names of channels that the requesting user/bot was not
authorized to subscribe to. Only present if `"authorization_errors_fatal": false`.
'
new_subscription_messages_sent:
type: boolean
description: 'Only present if the parameter `send_new_subscription_messages`
in the request was `true`.
Whether Notification Bot DMs in fact sent to the added
subscribers as requested by the `send_new_subscription_messages`
parameter. Clients may find this value useful to communicate
with users about the effect of this request.
**Changes**: New in Zulip 11.0 (feature level 397).
'
example:
already_subscribed:
'1':
- testing-help
msg: ''
result: success
subscribed:
'2':
- testing-help
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
msg: Unable to access channel (private).
result: error
code: BAD_REQUEST
description: 'An example JSON response for when the requesting user does not have
access to a private channel and `"authorization_errors_fatal": true`:
'
patch:
operationId: update-subscriptions
summary: Update subscriptions
tags:
- channels
description: 'Update which channels you are subscribed to.
**Changes**: Before Zulip 10.0 (feature level 362),
subscriptions in archived channels could not be modified.
'
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
delete:
description: 'A list of channel names to unsubscribe from.
'
type: array
items:
type: string
example:
- Verona
- Denmark
add:
description: 'A list of objects describing which channels to subscribe to, optionally
including per-user subscription parameters (e.g. color) and if the
channel is to be created, its description.
'
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
color:
type: string
description:
type: string
example:
- name: Verona
- name: Denmark
color: '#e79ab5'
description: A Scandinavian country
encoding:
delete:
contentType: application/json
add:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- required:
- subscribed
- already_subscribed
- removed
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
subscribed:
type: object
description: 'A dictionary where the key is the Zulip API email
address of the user/bot and the value is a
list of the names of the channels that were
subscribed to as a result of the query.
'
additionalProperties:
description: '`{email_id}`: A list of the names of channels that
the user was subscribed to as a result of the query.
'
type: array
items:
type: string
already_subscribed:
type: object
description: 'A dictionary where the key is the Zulip API email
address of the user/bot and the value is a
list of the names of the channels that the
user/bot is already subscribed to.
'
additionalProperties:
description: '`{email_id}`: A list of the names of channels that
the user was already subscribed to.
'
type: array
items:
type: string
not_removed:
type: array
items:
type: string
description: 'A list of the names of channels that the user
is already unsubscribed from, and hence
doesn''t need to be unsubscribed.
'
removed:
type: array
items:
type: string
description: 'A list of the names of channels which were unsubscribed
from as a result of the query
# --- truncated at 32 KB (175 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zulip/refs/heads/main/openapi/zulip-channels-api-openapi.yml