Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/zerver/openapi/zulip.yaml

23259 lines
1.1 MiB
Raw Blame History

# This file contains the API definitions for the Zulip REST API.
#
# For details on the OpenAPI specification, see https://swagger.io/specification
#
# Our own documentation lives at
#
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
#
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST 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:
# Zulip Cloud
- url: "https://{subdomain}.zulipchat.com/api/v1"
variables:
subdomain:
default: example
# Self-hosted
- url: "{server}/api/v1"
variables:
server:
default: https://
# chat.zulip.org
- url: "https://chat.zulip.org/api/v1"
# Development server
- url: "http://localhost:9991/api/v1"
# Test suite
- url: "http://{subdomain}.testserver/json"
security:
- basicAuth: []
#######################
# Endpoint definitions
#######################
paths:
/fetch_api_key:
post:
operationId: fetch-api-key
summary: Fetch an API key (production)
tags: ["authentication"]
description: |
This API endpoint is used by clients such as the Zulip mobile and
terminal apps to implement password-based authentication. Given the
user's Zulip login credentials, it returns a Zulip API key that the client
can use to make requests as the user.
This endpoint is only useful for Zulip servers/organizations with
EmailAuthBackend or LDAPAuthBackend enabled.
The Zulip mobile apps also support SSO/social authentication (GitHub
auth, Google auth, SAML, etc.) that does not use this endpoint. Instead,
the mobile apps reuse the web login flow passing the `mobile_flow_otp` in
a webview, and the credentials are returned to the app (encrypted) via a redirect
to a `zulip://` URL.
!!! warn ""
**Note:** If you signed up using passwordless authentication and
never had a password, you can [reset your password](/help/change-your-password).
See the [API keys](/api/api-keys) documentation for more details
on how to download an API key manually.
In a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
see also [the unauthenticated variant](/api/dev-fetch-api-key).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
description: |
The username to be used for authentication (typically, the email
address, but depending on configuration, it could be an LDAP username).
See the `require_email_format_usernames` parameter documented in
[GET /server_settings](/api/get-server-settings) for details.
type: string
example: iago@zulip.com
password:
type: string
example: abcd1234
description: |
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
required:
- username
- password
security: []
responses:
"200":
description: |
Valid credentials the client can use to access the Zulip API:
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeyResponse"
/dev_fetch_api_key:
post:
operationId: dev-fetch-api-key
summary: Fetch an API key (development only)
tags: ["authentication"]
description: |
For easy testing of mobile apps and other clients and against Zulip
development servers, we support fetching a Zulip API key for any user
on the development server without authentication (so that they can
implement analogues of the one-click login process available for Zulip
development servers on the web).
!!! warn ""
**Note:** This endpoint is only available on Zulip development
servers; for obvious security reasons it will always return an error
in a Zulip production server.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
description: |
The email address for the user that owns the API key.
type: string
example: iago@zulip.com
required:
- username
security: []
responses:
"200":
description: Success.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeyResponse"
/events:
get:
operationId: get-events
summary: Get events from an event queue
tags: ["real_time_events"]
description: |
This endpoint allows you to receive new events from
[a registered event queue](/api/register-queue).
Long-lived clients should use the
`event_queue_longpoll_timeout_seconds` property returned by
`POST /register` as the client-side HTTP request timeout for
calls to this endpoint. It is guaranteed to be higher than
heartbeat frequency and should be respected by clients to
avoid breaking when heartbeat frequency increases.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- queue_id
- last_event_id
x-parameter-description: |
!!! warn ""
**Note**: The parameters documented above are optional in the sense that
even if you haven't registered a queue by explicitly requesting the
`POST /register` endpoint, you could pass the parameters for
[the `POST /register` endpoint](/api/register-queue) to this
endpoint and a queue would be registered in the absence of a `queue_id`.
x-python-examples-extra-imports: ["sys"]
parameters:
- $ref: "#/components/parameters/QueueId"
- name: last_event_id
in: query
description: |
The highest event ID in this queue that you've received and
wish to acknowledge. See the [code for
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)
in the [zulip Python
module](https://github.com/zulip/python-zulip-api) for an
example implementation of correctly processing each event
exactly once.
schema:
type: integer
example: -1
- name: dont_block
in: query
description: |
Set to `true` if the client is requesting a nonblocking reply. If not
specified, the request will block until either a new event is available
or a few minutes have passed, in which case the server will send the
client a heartbeat event.
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: {}
events:
type: array
description: |
An array of `event` objects (possibly zero-length if `dont_block` is
set) with IDs newer than `last_event_id`. Event IDs are
guaranteed to be increasing, but they are not guaranteed to be
consecutive.
items:
oneOf:
- type: object
description: |
Event sent to a user's clients when that user's set of configured
[alert words](/help/dm-mention-alert-notifications#alert-words) have changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- alert_words
alert_words:
type: array
description: |
An array of strings, where each string is an alert word (or phrase)
configured by the user.
items:
type: string
additionalProperties: false
example:
{
"type": "alert_words",
"alert_words": ["alert_word"],
"id": 0,
}
- type: object
description: |
Event sent to clients that have requested the
`update_display_settings` event type and did not include
`user_settings_object` in their `client_capabilities` when
registering the event queue.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
deprecated: true
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_display_settings
user:
type: string
description: |
The Zulip API email of the user.
setting_name:
type: string
description: |
Name of the changed display setting.
setting:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: |
Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
type: string
additionalProperties: false
example:
{
"type": "update_display_settings",
"user": "iago@zulip.com",
"setting_name": "high_contrast_mode",
"setting": false,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's [notification
settings](/api/update-settings) have changed with an additional
rule that it is only sent to clients that did not include
`user_settings_object` in their `client_capabilities` when
registering the event queue.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
deprecated: true
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_global_notifications
user:
type: string
description: |
The Zulip API email of the user.
notification_name:
type: string
description: |
Name of the changed notification setting.
setting:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
additionalProperties: false
example:
{
"type": "update_global_notifications",
"user": "iago@zulip.com",
"notification_name": "enable_sounds",
"setting": true,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's settings
have changed.
**Changes**: New in Zulip 5.0 (feature level 89), replacing the
previous `update_display_settings` and `update_global_notifications`
event types, which are still present for backwards compatibility reasons.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_settings
op:
type: string
enum:
- update
property:
type: string
description: |
Name of the changed setting.
value:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: |
Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
type: string
additionalProperties: false
example:
{
"type": "user_settings",
"op": "update",
"property": "high_contrast_mode",
"value": false,
"id": 0,
}
- type: object
description: |
Event sent generally to all users who can access the modified
user for changes in the set of users or those users metadata.
**Changes**: Prior to Zulip 8.0 (feature level 228), this event
was sent to all users in the organization.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- update
person:
description: |
Object containing the changed details of the user.
It has multiple forms depending on the value changed.
oneOf:
- type: object
description: |
When a user changes their full name.
properties:
user_id:
type: integer
description: |
The ID of modified user.
full_name:
type: string
description: |
The new full name for the user.
additionalProperties: false
- type: object
description: |
When a user changes their avatar.
properties:
user_id:
type: integer
description: |
The ID of the user who is affected by this change.
avatar_url:
type: string
description: |
The URL of the new avatar for the user.
avatar_source:
type: string
description: |
The new avatar data source type for the user.
Value values are `G` (gravatar) and `U` (uploaded by user).
avatar_url_medium:
type: string
description: |
The new medium-size avatar URL for user.
avatar_version:
type: integer
description: |
The version number for the user's avatar. This is useful
for cache-busting.
additionalProperties: false
- type: object
additionalProperties: false
description: |
When a user changes their time zone setting.
properties:
user_id:
type: integer
description: |
The ID of modified user.
email:
type: string
description: |
The Zulip API email of the user.
**Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`.
deprecated: true
timezone:
type: string
description: |
The new time zone of the user.
- type: object
additionalProperties: false
description: |
When the owner of a bot changes.
properties:
user_id:
type: integer
description: |
The ID of the user/bot whose owner has changed.
bot_owner_id:
type: integer
description: |
The user ID of the new bot owner.
- type: object
additionalProperties: false
description: |
When the [role](/help/roles-and-permissions) of a user changes.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
role:
type: integer
description: |
The new [role](/api/roles-and-permissions) of the user.
enum:
- 100
- 200
- 300
- 400
- 600
- type: object
additionalProperties: false
description: |
When billing role of a user changes.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
is_billing_admin:
type: boolean
description: |
A boolean specifying whether the user is now a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
- type: object
additionalProperties: false
description: |
When the value of a user's delivery email as visible to you changes,
either due to the email address changing or your access to the user's
email changing via an update to their `email_address_visibility`
setting.
**Changes**: Prior to Zulip 7.0 (feature level 163), this event was
sent only to the affected user, and this event would only be triggered
by changing the affected user's delivery email.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
delivery_email:
type: string
nullable: true
description: |
The new delivery email of the user.
This value can be `null` if the affected user
changed their `email_address_visibility` setting
such that you cannot access their real email.
**Changes**: Before Zulip 7.0 (feature level 163),
`null` was not a possible value for this event as
it was only sent to the affected user when their
email address was changed.
- type: object
additionalProperties: false
description: |
When the user updates one of their custom profile
fields.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
custom_profile_field:
type: object
additionalProperties: false
description: |
Object containing details about the custom
profile data change.
properties:
id:
type: integer
description: |
The ID of the custom profile field which user updated.
value:
type: string
nullable: true
description: |
User's personal value for this custom profile field,
or `null` if unset.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support Markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
- type: object
additionalProperties: false
description: |
When the Zulip API email address of a user changes,
either due to the user's email address changing, or
due to changes in the user's
[email address visibility][help-email-visibility].
[help-email-visibility]: /help/configure-email-visibility
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
new_email:
type: string
description: |
The new value of `email` for the user. The client
should update any data structures associated
with this user to use this new value as the
user's Zulip API email address.
- type: object
additionalProperties: false
description: |
When a user is deactivated or reactivated.
**Changes**: New in Zulip 8.0 (feature level
222). Previously the server sent a `realm_user` event with
`op` field set to `remove` when deactivating a user and a
`realm_user` event with `op` field set to `add` when
reactivating a user.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
is_active:
type: boolean
description: |
A boolean describing whether the user account has been deactivated.
additionalProperties: false
example:
{
"type": "realm_user",
"op": "update",
"person":
{
"avatar_source": "G",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
"avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
"avatar_version": 3,
"user_id": 10,
},
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's channel subscriptions
have changed (either the set of subscriptions or their properties).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- add
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/Subscriptions"
additionalProperties: false
example:
{
"type": "subscription",
"op": "add",
"subscriptions":
[
{
"name": "test",
"stream_id": 9,
"creator_id": null,
"description": "",
"rendered_description": "",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
"color": "#76ce90",
"is_muted": false,
"pin_to_top": false,
"audible_notifications": null,
"desktop_notifications": null,
"email_notifications": null,
"push_notifications": null,
"wildcard_mentions_notify": null,
"in_home_view": true,
"stream_weekly_traffic": null,
"can_remove_subscribers_group": 2,
"subscribers": [10],
},
],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user has been unsubscribed
from one or more channels.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- remove
subscriptions:
type: array
description: |
A list of dictionaries, where each dictionary contains
information about one of the newly unsubscribed channels.
items:
type: object
additionalProperties: false
description: |
Dictionary containing details about the unsubscribed channel.
properties:
stream_id:
type: integer
description: |
The ID of the channel.
name:
type: string
description: |
The name of the channel.
additionalProperties: false
example:
{
"type": "subscription",
"op": "remove",
"subscriptions":
[{"name": "test", "stream_id": 9}],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when a property of the user's
subscription to a channel has been updated. This event is used
only for personal properties like `is_muted` or `pin_to_top`.
See the [`stream op: update` event](/api/get-events#stream-update)
for updates to global properties of a channel.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- update
stream_id:
type: integer
description: |
The ID of the channel whose subscription details have changed.
property:
type: string
description: |
The property of the subscription which has changed. For details on the
various subscription properties that a user can change, see
[POST /users/me/subscriptions/properties](/api/update-subscription-settings).
Clients should generally handle an unknown property received here without
crashing, since that will naturally happen when connecting to a Zulip
server running a new version that adds a new subscription property.
**Changes**: As of Zulip 6.0 (feature level 139), updates to the `is_muted`
property or the deprecated `in_home_view` property will send two `subscription`
update events, one for each property, to support clients fully migrating to
use the `is_muted` property. Prior to this feature level, updates to either
property only sent one event with the deprecated `in_home_view` property.
value:
description: |
The new value of the changed property.
oneOf:
- type: integer
- type: boolean
- type: string
additionalProperties: false
example:
{
"op": "update",
"type": "subscription",
"property": "pin_to_top",
"value": true,
"stream_id": 11,
"id": 0,
}
- type: object
description: |
Event sent when another user subscribes to a channel, or their
subscription is newly visible to the current user.
When a user subscribes to a channel, the current user will receive this
event only if they [have permission to see the channel's subscriber
list](/help/channel-permissions). When the current user gains permission
to see a given channel's subscriber list, they will receive this event
for the existing subscriptions to the channel.
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users when subscribers to web-public
channels and subscribed public channels changed.
Prior to Zulip 8.0 (feature level 205), this event was not sent when
a user gained access to a channel due to their [role
changing](/help/roles-and-permissions).
Prior to Zulip 6.0 (feature level 134), this event was not sent when a
private channel was made public.
In Zulip 4.0 (feature level 35), the singular `user_id` and `stream_id`
integers included in this event were replaced with plural `user_ids` and
`stream_ids` integer arrays.
In Zulip 3.0 (feature level 19), the `stream_id` field was added to
identify the channel the user subscribed to, replacing the `name` field.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- peer_add
stream_ids:
type: array
description: |
The IDs of channels that have new or updated subscriber data.
**Changes**: New in Zulip 4.0 (feature level 35), replacing
the `stream_id` integer.
items:
type: integer
user_ids:
type: array
description: |
The IDs of the users who are newly visible as subscribed to
the specified channels.
**Changes**: New in Zulip 4.0 (feature level 35), replacing
the `user_id` integer.
items:
type: integer
additionalProperties: false
example:
{
"type": "subscription",
"op": "peer_add",
"stream_ids": [9],
"user_ids": [12],
"id": 0,
}
- type: object
description: |
Event sent to other users when users have been unsubscribed
from channels. Sent to all users if the channel is public or to only
the existing subscribers if the channel is private.
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users when subscribers to web-public
channels and subscribed public channels changed.
In Zulip 4.0 (feature level 35), the singular `user_id` and
`stream_id` integers included in this event were replaced
with plural `user_ids` and `stream_ids` integer arrays.
In Zulip 3.0 (feature level 19), the `stream_id` field was
added to identify the channel the user unsubscribed from,
replacing the `name` field.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- peer_remove
stream_ids:
type: array
description: |
The IDs of the channels from which the users have been
unsubscribed from.
**Changes**: New in Zulip 4.0 (feature level 35), replacing
the `stream_id` integer.
items:
type: integer
user_ids:
type: array
description: |
The IDs of the users who have been unsubscribed.
**Changes**: New in Zulip 4.0 (feature level 35), replacing
the `user_id` integer.
items:
type: integer
additionalProperties: false
example:
{
"type": "subscription",
"op": "peer_remove",
"stream_ids": [9],
"user_ids": [12],
"id": 0,
}
- type: object
description: |
Event type for messages.
**Changes**: In Zulip 3.1 (feature level 26), the
`sender_short_name` field was removed from message
objects.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- message
message:
$ref: "#/components/schemas/MessagesEvent"
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
Clients should inspect the flags field rather than assuming that
new messages are unread; [muted users](/api/mute-user), messages
sent by the current user, and more subtle scenarios can result
in a new message that the server has already marked as read for
the user.
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
flag was deprecated in favor of the `stream_wildcard_mentioned` and
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
for backwards compatibility with older clients and equals
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
supporting older server versions should treat this field as a previous
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
were not available prior to this feature level.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
additionalProperties: false
example:
{
"type": "message",
"message":
{
"id": 31,
"sender_id": 10,
"content": '<p>First message ...<a href="user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt">zulip.txt</a></p>',
"recipient_id": 23,
"timestamp": 1594825416,
"client": "test suite",
"subject": "test",
"topic_links": [],
"is_me_message": false,
"reactions": [],
"submessages": [],
"sender_full_name": "King Hamlet",
"sender_email": "user10@zulip.testserver",
"sender_realm_str": "zulip",
"display_recipient": "Denmark",
"type": "stream",
"stream_id": 1,
"avatar_url": null,
"content_type": "text/html",
},
"flags": [],
"id": 1,
}
- type: object
description: |
Event sent to a user's clients when the user completes the
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
to know whether initiating Zoom OAuth is required before creating a Zoom call.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- has_zoom_token
value:
type: boolean
description: |
A boolean specifying whether the user has zoom
token or not.
additionalProperties: false
example:
{
"type": "has_zoom_token",
"value": true,
"id": 0,
}
- type: object
description: |
A simple event sent when the set of invitations changes.
This event is sent to organization administrators and the creator of
the changed invitation; this tells clients they need to refetch
data from `GET /invites` if they are displaying UI containing active
invitations.
**Changes**: Before Zulip 8.0 (feature level 209), this event was
only sent to organization administrators.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- invites_changed
additionalProperties: false
example: {"type": "invites_changed", "id": 0}
- type: object
description: |
Event sent to all users in a Zulip organization when a new
user joins or when a guest user gains access to a user.
Processing this event is important to being able to display
basic details on other users given only their ID.
If the current user is a guest whose access to a newly created user
is limited by a `can_access_all_users_group` policy, and the event
queue was registered with the `user_list_incomplete` client
capability, then the event queue will not receive an event for such
a new user. If a newly created user is inaccessible to the current
user via such a policy, but the client lacks `user_list_incomplete`
client capability, then this event will be delivered to the queue,
with an "Unknown user" object with the usual format but placeholder
data whose only variable content is the user ID.
**Changes**: Before Zulip 8.0 (feature level 232), the
`user_list_incomplete` client capability did not exist, and so all
clients whose access to a new user was prevented by
`can_access_all_users_group` policy would receive a fake "Unknown
user" event for such a user.
Starting with Zulip 8.0 (feature level 228),
this event is also sent when a guest user gains access to
a user.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- add
person:
$ref: "#/components/schemas/User"
additionalProperties: false
example:
{
"type": "realm_user",
"op": "add",
"person":
{
"email": "foo@zulip.com",
"delivery_email": null,
"user_id": 38,
"avatar_version": 1,
"is_admin": false,
"is_owner": false,
"is_guest": false,
"is_billing_admin": false,
"role": 400,
"is_bot": false,
"full_name": "full name",
"timezone": "",
"is_active": true,
"date_joined": "2020-07-15T15:04:02.030833+00:00",
"avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
"profile_data": {},
},
"id": 0,
}
- type: object
description: |
Event sent to guest users when they lose access to a user.
**Changes**: As of Zulip 8.0 (feature level 228), this event is no
longer deprecated.
In Zulip 8.0 (feature level 222), this event was deprecated and no
longer sent to clients. Prior to this feature level, it was sent to all
users in a Zulip organization when a user was deactivated.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- remove
person:
type: object
additionalProperties: false
description: |
Object containing details of the deactivated user.
properties:
user_id:
type: integer
description: |
The ID of the deactivated user.
full_name:
type: string
deprecated: true
description: |
The full name of the user.
**Deprecated**: We expect to remove this field in the future.
additionalProperties: false
example:
{
"type": "realm_user",
"op": "remove",
"person":
{"user_id": 35, "full_name": "Foo Bot"},
"id": 0,
}
- type: object
description: |
Event sent to all users in an organization when a user comes
back online after being offline for a while. While most presence
updates are done via polling the [main presence
endpoint](/api/get-presence), this event is important to avoid
confusing users when someone comes online and immediately sends
a message (one wouldn't want them to still appear offline at
that point!).
If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level
setting is set to `true`, then the event is only sent to users
who can access the user who came back online.
**Changes**: Prior to Zulip 8.0 (feature level 228), this event
was sent to all users in the organization.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- presence
user_id:
type: integer
description: |
The ID of the modified user.
email:
type: string
description: |
The Zulip API email of the user.
**Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`.
deprecated: true
server_timestamp:
type: number
description: |
The timestamp of when the Zulip server received the user's
presence as a UNIX timestamp.
presence:
type: object
description: |
Object containing the details of the user's most recent presence.
additionalProperties:
type: object
description: |
`{client_name}`: Object containing the details of the user's
presence.
**Changes**: Starting with Zulip 7.0 (feature level 178), this
will always be `"website"` as the server no longer stores which
client submitted presence updates.
Previously, the object key was the client's platform name, for
example `website` or `ZulipDesktop`.
additionalProperties: false
properties:
client:
type: string
description: |
The client's platform name.
**Changes**: Starting with Zulip 7.0 (feature level 178), this
will always be `"website"` as the server no longer stores which
client submitted presence updates.
status:
type: string
enum:
- idle
- active
description: |
The status of the user on this client. Will be either `idle`
or `active`.
timestamp:
type: integer
description: |
The UNIX timestamp of when this client sent the user's presence
to the server with the precision of a second.
pushable:
type: boolean
description: |
Whether the client is capable of showing mobile/push notifications
to the user.
**Changes**: Starting with Zulip 7.0 (feature level 178), this
will always be `false` as the server no longer stores which
client submitted presence updates.
additionalProperties: false
example:
{
"type": "presence",
"user_id": 10,
"email": "user10@zulip.testserver",
"server_timestamp": 1594825445.320078373,
"presence":
{
"website":
{
"client": "website",
"status": "idle",
"timestamp": 1594825445,
"pushable": false,
},
},
"id": 0,
}
- type: object
description: |
Event sent when a new channel is created to users who can see
the new channel exists (for private channels, only subscribers and
organization administrators will receive this event).
This event is also sent when a user gains access to a channel they
previously [could not access](/help/channel-permissions), such as
when their [role](/help/roles-and-permissions) changes, a
private channel is made public, or a guest user is subscribed
to a public (or private) channel.
Note that organization administrators who are not subscribed will
not be able to see content on the channel; just that it exists.
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users a web-public channel was created.
Prior to Zulip 8.0 (feature level 205), this event was not sent
when a user gained access to a channel due to their role changing.
Prior to Zulip 8.0 (feature level 192), this event was not sent
when guest users gained access to a public channel by being
subscribed.
Prior to Zulip 6.0 (feature level 134), this event was not sent
when a private channel was made public.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- create
streams:
type: array
description: |
Array of objects, each containing
details about the newly added channel(s).
items:
$ref: "#/components/schemas/BasicChannel"
additionalProperties: false
example:
{
"type": "stream",
"op": "create",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"date_created": 1691057093,
"creator_id": 11,
"invite_only": true,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": false,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
"stream_weekly_traffic": null,
},
],
"id": 0,
}
- type: object
description: |
Event sent to all users who can see a channel when it is deactivated.
This event is also sent when a user loses access to a channel they
previously [could access](/help/channel-permissions) because they
are unsubscribed from a private channel or their [role](/help/roles-and-permissions)
has changed.
**Changes**: Prior to Zulip 8.0 (feature level 205), this event was
not sent when a user lost access to a channel due to their role
changing.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- delete
streams:
type: array
description: |
Array of objects, each containing
details about a channel that was deleted.
items:
$ref: "#/components/schemas/BasicChannel"
additionalProperties: false
example:
{
"type": "stream",
"op": "delete",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"date_created": 1691057093,
"creator_id": 11,
"invite_only": true,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": false,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
"stream_weekly_traffic": null,
},
],
"id": 0,
}
- type: object
description: |
Event sent to all users who can see that a channel exists
when a property of that channel changes. See
[GET /streams](/api/get-streams#response) response
for details on the various properties of a channel.
**Changes**: Before Zulip 9.0 (feature level 256), this event
was never sent when the `first_message_id` property of a channel
was updated because the oldest message that had been sent to it
changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- update
stream_id:
type: integer
description: |
The ID of the channel whose details have changed.
name:
type: string
description: |
The name of the channel whose details have changed.
property:
type: string
description: |
The property of the channel which has changed. See
[GET /streams](/api/get-streams#response) response for details
on the various properties of a channel.
Clients should handle an "unknown" property received here without
crashing, since that can happen when connecting to a server running a
newer version of Zulip with new features.
value:
description: |
The new value of the changed property.
oneOf:
- type: integer
- type: boolean
- type: string
rendered_description:
type: string
description: |
Note: Only present if the changed property was `description`.
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.
history_public_to_subscribers:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
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.
is_web_public:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
Whether the channel's history is now readable by web-public spectators.
**Changes**: New in Zulip 5.0 (feature level 71).
additionalProperties: false
example:
{
"op": "update",
"type": "stream",
"property": "invite_only",
"value": true,
"history_public_to_subscribers": true,
"is_web_public": false,
"stream_id": 11,
"name": "test",
"id": 0,
}
- type: object
description: |
Event sent when a reaction is added to a message.
Sent to all users who were recipients of the message.
allOf:
- $ref: "#/components/schemas/EmojiReactionEvent"
- additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- reaction
op:
type: string
enum:
- add
message_id:
type: integer
description: |
The ID of the message to which a reaction was
added.
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id: {}
user: {}
example:
{
"type": "reaction",
"op": "add",
"user_id": 10,
"user":
{
"user_id": 10,
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
},
"message_id": 32,
"emoji_name": "tada",
"emoji_code": "1f389",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
description: |
Event sent when a reaction is removed from a message.
Sent to all users who were recipients of the message.
allOf:
- $ref: "#/components/schemas/EmojiReactionEvent"
- additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- reaction
op:
type: string
enum:
- remove
message_id:
type: integer
description: |
The ID of the message from which the reaction was
removed.
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id: {}
user: {}
example:
{
"type": "reaction",
"op": "remove",
"user_id": 10,
"user":
{
"user_id": 10,
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
},
"message_id": 52,
"emoji_name": "tada",
"emoji_code": "1f389",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when the user uploads a new file
in a Zulip message. Useful to implement live update in UI showing all files
the current user has uploaded.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- add
attachment:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "add",
"attachment":
{
"id": 1,
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6,
"create_time": 1594825414000,
"messages": [],
},
"upload_space_used": 6,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when details of a file that user
uploaded are changed. Most updates will be changes in the list of
messages that reference the uploaded file.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- update
attachment:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "update",
"attachment":
{
"id": 1,
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6,
"create_time": 1594825414000,
"messages": [],
},
"upload_space_used": 6,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when the user deletes a file
they had uploaded. Useful primarily for UI showing all the files
the current user has uploaded.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- remove
attachment:
type: object
description: |
Dictionary containing the ID of the deleted attachment.
additionalProperties: false
properties:
id:
type: integer
description: |
The ID of the deleted attachment.
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "remove",
"attachment": {"id": 1},
"upload_space_used": 0,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a submessage is added to a message.
Submessages are an **experimental** API used for widgets such as the
`/poll` widget in Zulip.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- submessage
msg_type:
type: string
description: |
The type of the message.
content:
type: string
description: |
The new content of the submessage.
message_id:
type: integer
description: |
The ID of the message to which the submessage has been added.
sender_id:
type: integer
description: |
The ID of the user who sent the message.
submessage_id:
type: integer
description: |
The ID of the submessage.
example:
{
"type": "submessage",
"msg_type": "widget",
"message_id": 970461,
"submessage_id": 4737,
"sender_id": 58,
"content": '{"type":"vote","key":"58,1","vote":1}',
"id": 28,
}
- type: object
additionalProperties: false
description: |
Event sent to all users who can access the modified
user when the status of a user changes.
**Changes**: Prior to Zulip 8.0 (feature level 228),
this event was sent to all users in the organization.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_status
away:
type: boolean
deprecated: true
description: |
Whether the user has marked themself "away" with this status.
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
starting with that feature level, `away` is a legacy way to
access the user's `presence_enabled` setting, with
`away = !presence_enabled`. To be removed in a future release.
status_text:
type: string
description: |
The text content of the status message.
This will be `""` for users who set a status without selecting
or writing a message.
emoji_name:
type: string
description: |
The [emoji name](/api/update-status#parameter-emoji_name) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
emoji_code:
type: string
description: |
The [emoji code](/api/update-status#parameter-emoji_code) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
reaction_type:
type: string
enum:
- unicode_emoji
- realm_emoji
- zulip_extra_emoji
description: |
The [emoji type](/api/update-status#parameter-reaction_type) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
user_id:
type: integer
description: |
The ID of the user whose status changed.
example:
{
"type": "user_status",
"user_id": 10,
"away": true,
"status_text": "out to lunch",
"emoji_name": "car",
"emoji_code": "1f697",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when new custom
profile field types are configured for that Zulip organization.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- custom_profile_fields
fields:
type: array
description: |
An array of dictionaries where each dictionary contains
details of a single new custom profile field for the Zulip
organization.
items:
$ref: "#/components/schemas/CustomProfileField"
example:
{
"type": "custom_profile_fields",
"fields":
[
{
"id": 1,
"name": "Phone number",
"type": 1,
"hint": "",
"field_data": "",
"order": 1,
"required": true,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
"required": true,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
"required": false,
},
{
"id": 4,
"name": "Favorite editor",
"type": 3,
"hint": "",
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
"order": 4,
"display_in_profile_summary": true,
"required": true,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
"required": false,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
"display_in_profile_summary": true,
"required": false,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
"required": true,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
"required": true,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when an organization
administrator changes the organization's configured default channel groups.
Default channel groups are an **experimental** feature that is not yet
stabilized.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- default_stream_groups
default_stream_groups:
type: array
description: |
An array of dictionaries where each dictionary
contains details about a single default channel group.
items:
$ref: "#/components/schemas/DefaultChannelGroup"
example:
{
"type": "default_stream_groups",
"default_stream_groups":
[
{
"name": "group1",
"id": 2,
"description": "New description",
"streams":
[
{
"name": "Scotland",
"stream_id": 3,
"description": "Located in the United Kingdom",
"rendered_description": "<p>Located in the United Kingdom</p>",
"date_created": 1691057093,
"creator_id": 8,
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 1,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
},
{
"name": "Denmark",
"stream_id": 1,
"description": "A Scandinavian country",
"rendered_description": "<p>A Scandinavian country</p>",
"date_created": 1691057093,
"creator_id": null,
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 4,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
},
{
"name": "Verona",
"stream_id": 5,
"description": "A city in Italy",
"rendered_description": "<p>A city in Italy</p>",
"date_created": 1691057093,
"creator_id": 9,
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 6,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
},
],
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
default channels in the organization are changed by an
organization administrator.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- default_streams
default_streams:
type: array
description: |
An array of dictionaries where each dictionary
contains details about a single default channel.
items:
$ref: "#/components/schemas/DefaultChannel"
example:
{
"type": "default_streams",
"default_streams":
[
{
"name": "Scotland",
"stream_id": 3,
"description": "Located in the United Kingdom",
"rendered_description": "<p>Located in the United Kingdom</p>",
"date_created": 1691057093,
"creator_id": 8,
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 1,
"message_retention_days": null,
"is_announcement_only": false,
"can_remove_subscribers_group": 2,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a message has been deleted.
Sent to all users who currently are subscribed to the
messages' recipient. May also be sent to additional users
who had access to it, including, in particular, an
administrator user deleting messages in a stream that they
are not subscribed to.
This means that clients can assume that they will always
receive an event of this type for deletions that the
client itself initiated.
This event is also sent when the user loses access to a message,
such as when it is [moved to a channel][message-move-channel] that
the user does not [have permission to access][channel-access].
**Changes**: Before Zulip 9.0 (feature level 274), this
event was only sent to subscribers of the message's recipient.
Before Zulip 5.0 (feature level 77), events
for direct messages contained additional `sender_id` and
`recipient_id` fields.
[message-move-channel]: /help/move-content-to-another-channel
[channel-access]: /help/channel-permissions
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- delete_message
message_ids:
type: array
description: |
Only present for clients that support the `bulk_message_deletion`
[client capability][client-capabilities].
A list containing the IDs of the newly deleted messages.
[client-capabilities]: /api/register-queue#parameter-client_capabilities
items:
type: integer
message_id:
type: integer
description: |
Only present for clients that do not support the `bulk_message_deletion`
[client capability][client-capabilities].
The ID of the newly deleted message.
[client-capabilities]: /api/register-queue#parameter-client_capabilities
message_type:
type: string
description: |
The type of message. Either `"stream"` or `"private"`.
enum:
- private
- stream
stream_id:
type: integer
description: |
Only present if `message_type` is `"stream"`.
The ID of the channel to which the message was sent.
topic:
type: string
description: |
Only present if `message_type` is `"stream"`.
The topic to which the message was sent.
example:
{
"type": "delete_message",
"message_type": "private",
"message_id": 37,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's set of
configured muted topics have changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- muted_topics
muted_topics:
type: array
deprecated: true
description: |
Array of tuples, where each tuple describes a muted topic.
The first element of the tuple is the channel name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
**Changes**: Deprecated in Zulip 6.0 (feature level
134). Starting with this version, clients that explicitly
requested the replacement `user_topic` event type when
registering their event queue will not receive this legacy
event type.
Before Zulip 3.0 (feature level 1), the `muted_topics`
array objects were 2-item tuples and did not include the timestamp
information for when the topic was muted.
items:
type: array
items:
oneOf:
- type: string
- type: integer
additionalProperties: false
example:
{
"type": "muted_topics",
"muted_topics":
[["Denmark", "topic", 1594825442]],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when the user mutes/unmutes
a topic, or otherwise modifies their personal per-topic
configuration.
**Changes**: New in Zulip 6.0 (feature level 134). Previously,
clients were notified about changes in muted topic
configuration via the `muted_topics` event type.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_topic
stream_id:
type: integer
description: |
The ID of the channel to which the topic belongs.
topic_name:
type: string
description: |
The name of the topic.
last_updated:
type: integer
description: |
An integer UNIX timestamp representing when the user-topic
relationship was last changed.
visibility_policy:
type: integer
description: |
An integer indicating the user's visibility
preferences for the topic, such as whether the topic
is muted.
- 0 = None. Used to indicate that the user no
longer has a special visibility policy for this topic.
- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).
- 2 = Unmuted. Used to record unmuted topics.
- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).
**Changes**: In Zulip 7.0 (feature level 219), added followed as
a visibility policy option.
In Zulip 7.0 (feature level 170), added unmuted as a visibility
policy option.
additionalProperties: false
example:
{
"id": 1,
"type": "user_topic",
"stream_id": 1,
"topic_name": "topic",
"last_updated": 1594825442,
"visibility_policy": 1,
}
- type: object
description: |
Event sent to a user's clients when that user's set of
configured [muted users](/api/mute-user) have changed.
**Changes**: New in Zulip 4.0 (feature level 48).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- muted_users
muted_users:
type: array
description: |
A list of dictionaries where each dictionary describes
a muted user.
items:
type: object
additionalProperties: false
description: |
Object containing the user ID and timestamp of a muted user.
properties:
id:
type: integer
description: |
The ID of the muted user.
timestamp:
type: integer
description: |
An integer UNIX timestamp representing when the user was muted.
additionalProperties: false
example:
{
"type": "muted_users",
"muted_users":
[
{"id": 1, "timestamp": 1594825442},
{"id": 22, "timestamp": 1654865392},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Heartbeat events are sent by the server to avoid
longpolling connections being affected by networks that
kill idle HTTP connections.
Clients do not need to do anything to process these
events, beyond the common `last_event_id` accounting.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- heartbeat
example: {"type": "heartbeat", "id": 0}
- type: object
additionalProperties: false
description: |
Event sent when the set of onboarding steps to show for the current user
has changed (e.g. because the user dismissed one).
Clients that feature a similar tutorial experience to the Zulip web app
may want to handle these events.
**Changes**: Before Zulip 8.0 (feature level 233), this event was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- onboarding_steps
onboarding_steps:
type: array
description: |
An array of dictionaries where each dictionary contains details about a
single onboarding step.
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported, and the `type` field in these objects did not
exist as all onboarding steps were implicitly hotspots.
items:
$ref: "#/components/schemas/OnboardingStep"
example:
{
"type": "onboarding_steps",
"onboarding_steps":
[
{
"type": "one_time_notice",
"name": "visibility_policy_banner",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a message's content, topic and/or
channel has been edited or when a message's content
has a rendering update, such as for an
[inline URL preview][inline-url-previews].
Sent to all users who had received the original
message.
[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message
user_id:
type: integer
nullable: true
description: |
The ID of the user who sent the message.
Is `null` when event is for a rendering update of the original message,
such as for an [inline URL preview][inline-url-previews].
**Changes**: As of Zulip 5.0 (feature level 114), this field
is present for all `update_message` events. Previously, this
field was omitted for [inline URL preview][inline-url-previews]
updates.
rendering_only:
type: boolean
description: |
Whether the event only updates the rendered content of the message.
This field should be used by clients to determine if the event
only provides a rendering update to the message content,
such as for an [inline URL preview][inline-url-previews].
When `true`, the event does not reflect a user-generated edit
and does not modify the message history.
**Changes**: New in Zulip 5.0 (feature level 114). Clients can
correctly identify these rendering update event with earlier
Zulip versions by checking whether the `user_id` field was omitted.
message_id:
type: integer
description: |
The ID of the message which was edited or updated.
This field should be used to apply content edits to the client's
cached message history, or to apply rendered content updates.
If the channel or topic was changed, the set of moved messages is
encoded in the separate `message_ids` field, which is guaranteed
to include `message_id`.
message_ids:
type: array
items:
type: integer
description: |
The list of IDs of messages to which any channel or topic changes
encoded in this event should be applied.
This list always includes `message_id`, even when there are no
channel or topic changes to apply.
These messages are guaranteed to have all been previously sent
to channel `stream_id` with topic `orig_subject`, and have been
moved to `new_stream_id` with topic `subject` (if those fields
are present in the event).
Clients processing these events should update all cached message
history associated with the moved messages (including adjusting
`unread_msgs` data structures, where the client may not have the
message itself in its history) to reflect the new channel and
topic.
Content changes should be applied only to the single message
indicated by `message_id`.
flags:
type: array
description: |
The user's personal [message flags][message-flags] for the
message with ID `message_id` following the edit.
A client application should compare these to the original flags
to identify cases where a mention or alert word was added by the
edit.
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
flag was deprecated in favor of the `stream_wildcard_mentioned` and
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
for backwards compatibility with older clients and equals
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
supporting older server versions should treat this field as a previous
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
were not available prior to this feature level.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
edit_timestamp:
type: integer
description: |
The time when this message edit operation was processed by the
server.
**Changes**: As of Zulip 5.0 (feature level 114), this field
is present for all `update_message` events. Previously, this
field was omitted for [inline URL preview][inline-url-previews]
updates.
stream_name:
type: string
description: |
Only present if the message was edited and originally sent to a channel.
The name of the channel that the message was sent to. Clients
are recommended to use the `stream_id` field instead.
stream_id:
type: integer
description: |
Only present if the message was edited and originally sent to a channel.
The pre-edit channel for all of the messages with IDs in
`message_ids`.
**Changes**: As of Zulip 5.0 (feature level 112), this field
is present for all edits to a channel message. Previously, it
was not present when only the content of the channel message was
edited.
new_stream_id:
type: integer
description: |
Only present if message(s) were moved to a different channel.
The post-edit channel for all of the messages with IDs in
`message_ids`.
propagate_mode:
type: string
description: |
Only present if this event moved messages to a different
topic and/or channel.
The choice the editing user made about which messages should be
affected by a channel/topic edit:
- `"change_one"`: Just change the one indicated in `message_id`.
- `"change_later"`: Change messages in the same topic that had
been sent after this one.
- `"change_all"`: Change all messages in that topic.
This parameter should be used to decide whether to change
navigation and compose box state in response to the edit. For
example, if the user was previously in topic narrow, and the
topic was edited with `"change_later"` or `"change_all"`, the Zulip
web app will automatically navigate to the new topic narrow.
Similarly, a message being composed to the old topic should
have its recipient changed to the new topic.
This navigation makes it much more convenient to move content
between topics without disruption or messages continuing
to be sent to the pre-edit topic by accident.
enum:
- change_one
- change_later
- change_all
orig_subject:
type: string
description: |
Only present if this event moved messages to a different
topic and/or channel.
The pre-edit topic for all of the messages with IDs in
`message_ids`.
subject:
type: string
description: |
Only present if this event moved messages to a different topic;
this field will not be present when moving messages to the same
topic name in a different channel.
The post-edit topic for all of the messages with IDs in
`message_ids`.
topic_links:
type: array
items:
type: object
additionalProperties: false
properties:
text:
type: string
description: |
The original link text present in the topic.
url:
type: string
description: |
The expanded target url which the link points to.
description: |
Only present if this event moved messages to a different topic;
this field will not be present when moving messages to the same
topic name in a different channel.
Data on any links to be included in the `topic`
line (these are generated by
[custom linkification filter](/help/add-a-custom-linkifier)
that match content in the message's topic.), corresponding
to the post-edit topic.
**Changes**: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1). Previously, this field
was called `subject_links`; clients are recommended to
rename `subject_links` to `topic_links` if present for
compatibility with older Zulip servers.
orig_content:
type: string
description: |
Only present if this event changed the message content.
The original content of the message with ID `message_id`
immediately prior to this edit, in the original markdown.
orig_rendered_content:
type: string
description: |
Only present if this event changed the message content.
The original content of the message with ID `message_id`
immediately prior to this edit, rendered as HTML.
prev_rendered_content_version:
type: integer
description: |
Only present if this event changed the message content.
The Markdown processor version number for the pre-edit message.
Clients should ignore this field.
content:
type: string
description: |
Only present if this event changed the message content or
updated the message content for an
[inline URL preview][inline-url-previews].
The new content of the message with ID `message_id`, in the
original Markdown.
rendered_content:
type: string
description: |
Only present if this event changed the message content or
updated the message content for an
[inline URL preview][inline-url-previews].
The new content of the message with ID `message_id`,
rendered in HTML.
is_me_message:
type: boolean
description: |
Only present if this event changed the message content.
Whether the message with ID `message_id` is now a
[/me status message][status-messages].
[status-messages]: /help/format-your-message-using-markdown#status-messages
required:
- type
- id
- user_id
- message_id
- message_ids
- flags
- edit_timestamp
- rendering_only
example:
{
"type": "update_message",
"user_id": 10,
"edit_timestamp": 1594825451,
"message_id": 58,
"stream_name": "Verona",
"orig_content": "hello",
"orig_rendered_content": "<p>hello</p>",
"content": "new content",
"rendered_content": "<p>new content</p>",
"prev_rendered_content_version": 1,
"is_me_message": false,
"propagate_mode": "change_all",
"stream_id": 5,
"orig_subject": "test",
"subject": "new_topic",
"topic_links": [],
"message_ids": [58, 57],
"flags": [],
"rendering_only": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a user starts typing a message.
Sent to all clients for users who would receive the
message being typed, with the additional rule that typing
notifications for channel messages are only sent to clients
that included `stream_typing_notifications` in their
[client capabilities][client-capabilities] when registering
the event queue.
See [POST /typing](/api/set-typing-status) endpoint for more details.
**Changes**: Typing notifications for channel messages are new in
Zulip 4.0 (feature level 58).
[client-capabilities]: /api/register-queue#parameter-client_capabilities
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- typing
op:
type: string
enum:
- start
message_type:
type: string
description: |
Type of message being composed. Must be `"stream"` or `"direct"`.
**Changes**: In Zulip 8.0 (feature level 215), replaced the
value `"private"` with `"direct"`.
New in Zulip 4.0 (feature level 58). Previously, all typing
notifications were implicitly direct messages.
enum:
- direct
- stream
sender:
additionalProperties: false
type: object
description: |
Object describing the user who is typing the message.
properties:
user_id:
type: integer
description: |
The user's ID.
email:
type: string
description: |
The Zulip API email address for the user.
recipients:
type: array
description: |
Only present if `message_type` is `"direct"`.
Array of dictionaries describing the set of users who would be
recipients of the message being typed. Each dictionary contains
details about one of the recipients. The sending user is guaranteed
to appear among the recipients.
items:
type: object
additionalProperties: false
description: |
Object containing the user ID and Zulip API email of a recipient.
properties:
user_id:
type: integer
description: |
The ID of the user.
email:
type: string
description: |
The Zulip API email address for the user.
stream_id:
type: integer
description: |
Only present if `message_type` is `"stream"`.
The unique ID of the channel to which message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
topic:
type: string
description: |
Only present if `message_type` is `"stream"`.
Topic within the channel where the message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
example:
{
"type": "typing",
"op": "start",
"message_type": "direct",
"sender":
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
"recipients":
[
{
"user_id": 8,
"email": "user8@zulip.testserver",
},
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a user stops typing a message.
Sent to all clients for users who would receive the message
that was previously being typed, with the additional rule
that typing notifications for channel messages are only sent to
clients that included `stream_typing_notifications` in their
[client capabilities][client-capabilities] when registering
the event queue.
See [POST /typing](/api/set-typing-status) endpoint for more details.
**Changes**: Typing notifications for channel messages are new in
Zulip 4.0 (feature level 58).
[client-capabilities]: /api/register-queue#parameter-client_capabilities
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- typing
op:
type: string
enum:
- stop
message_type:
type: string
description: |
Type of message being composed. Must be `"stream"` or `"direct"`.
**Changes**: In Zulip 8.0 (feature level 215), replaced the
value `"private"` with `"direct"`.
New in Zulip 4.0 (feature level 58). Previously all typing
notifications were implicitly direct messages.
enum:
- direct
- stream
sender:
additionalProperties: false
type: object
description: |
Object describing the user who was previously typing the message.
properties:
user_id:
type: integer
description: |
The user's ID.
email:
type: string
description: |
The Zulip API email address for the user.
recipients:
type: array
description: |
Only present if `message_type` is `"direct"`.
Array of dictionaries describing the set of users who would be
recipients of the message that was previously being typed. Each
dictionary contains details about one of the recipients. The
sending user is guaranteed to appear among the recipients.
items:
type: object
additionalProperties: false
description: |
Object containing the user ID and email of a recipient.
properties:
user_id:
type: integer
description: |
The ID of the user.
email:
type: string
description: |
The Zulip API email address for the user.
stream_id:
type: integer
description: |
Only present if `message_type` is `"stream"`.
The unique ID of the channel to which message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
topic:
type: string
description: |
Only present if `message_type` is `"stream"`.
Topic within the channel where the message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for direct messages.
example:
{
"type": "typing",
"op": "stop",
"message_type": "direct",
"sender":
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
"recipients":
[
{
"user_id": 8,
"email": "user8@zulip.testserver",
},
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user when [message flags][message-flags] are added
to messages.
This can reflect a direct user action, or can be the indirect
consequence of another action. Whatever the cause, if there's a change
in the set of message flags that the user has for a message, then an
`update_message_flags` event will be sent with the change. Note
that this applies when the user already had access to the message, and
continues to have access to it. When a message newly appears or
disappears, a [`message`][message-event] or
[`delete_message`][message-delete] event is sent instead.
Some examples of actions that trigger an `update_message_flags`
event:
- The `"starred"` flag is added when the user chooses to [star a
message](/help/star-a-message).
- The `"read"` flag is added when the user marks messages as read by
scrolling through them, or uses [Mark all messages as read][all-read]
on a conversation.
- The `"read"` flag is added when the user [mutes](/help/mute-a-user) a
message's sender.
- The `"read"` flag is added after the user unsubscribes from a channel,
or messages are moved to a not-subscribed channel, provided the user
can still access the messages at all. Note a
[`delete_message`][message-delete] event is sent in the case where the
user can no longer access the messages.
In some cases, a change in message flags that's caused by another change
may happen a short while after the original change, rather than
simultaneously. For example, when messages that were unread are moved to
a channel where the user is not subscribed, the resulting change in
message flags (and the corresponding `update_message_flags` event with
flag `"read"`) may happen later than the message move itself. The delay
in that example is typically at most a few hundred milliseconds and can
in rare cases be minutes or longer.
[message-flags]: /api/update-message-flags#available-flags
[message-event]: /api/get-events#message
[message-delete]: /api/get-events#delete_message
[all-read]: /help/marking-messages-as-read#mark-all-messages-as-read
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message_flags
op:
type: string
enum:
- add
operation:
deprecated: true
description: |
Old name for the `op` field in this event type.
**Deprecated** in Zulip 4.0 (feature level 32), and
replaced by the `op` field.
type: string
enum:
- add
flag:
type: string
description: |
The [flag][message-flags] that was added.
messages:
type: array
description: |
Array containing the IDs of all messages to which
the flag was added.
items:
type: integer
all:
type: boolean
description: |
Whether the specified flag was added to all messages.
This field is only relevant for the `"read"` flag, and
will be `false` for all other flags.
When `true` for the `"read"` flag, then the `messages`
array will be empty.
example:
{
"type": "update_message_flags",
"op": "add",
"operation": "add",
"flag": "starred",
"messages": [63],
"all": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user when [message flags][message-flags] are
removed from messages.
See the description for the [`update_message_flags` op:
`add`](/api/get-events#update_message_flags-add) event for
more details about these events.
[message-flags]: /api/update-message-flags#available-flags
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message_flags
op:
type: string
enum:
- remove
operation:
deprecated: true
type: string
description: |
Old name for the `op` field in this event type.
**Deprecated** in Zulip 4.0 (feature level 32), and
replaced by the `op` field.
enum:
- remove
flag:
type: string
description: |
The [flag][message-flags] to be removed.
messages:
type: array
description: |
Array containing the IDs of the messages from which the flag
was removed.
items:
type: integer
all:
deprecated: true
type: boolean
description: |
Will be `false` for all specified flags.
**Deprecated** and will be removed in a future release.
message_details:
description: |
Only present if the specified `flag` is `"read"`.
A set of data structures describing the messages that
are being marked as unread with additional details to
allow clients to update the `unread_msgs` data
structure for these messages (which may not be
otherwise known to the client).
**Changes**: New in Zulip 5.0 (feature level 121). Previously,
marking already read messages as unread was not
supported by the Zulip API.
type: object
additionalProperties:
type: object
description: |
`{message_id}`: Object containing details about the
message with the specified ID.
additionalProperties: false
required: ["type"]
properties:
type:
type: string
description: |
The type of this message. Either `"stream"` or `"private"`.
enum:
- private
- stream
mentioned:
type: boolean
description: |
A flag which indicates whether the message contains a mention
of the user.
Present only if the message mentions the current user.
user_ids:
type: array
items:
type: integer
description: |
Present only if `type` is `private`.
The user IDs of every recipient of this direct message, excluding yourself.
Will be the empty list for a message you had sent to only yourself.
stream_id:
type: integer
description: |
Present only if `type` is `"stream"`.
The ID of the channel where the message was sent.
topic:
type: string
description: |
Present only if `type` is `"stream"`.
Name of the topic where the message was sent.
unmuted_stream_msg:
type: boolean
deprecated: true
description: |
**Deprecated** internal implementation detail. Clients should
ignore this field as it will be removed in the future.
example:
{
"type": "update_message_flags",
"op": "remove",
"operation": "remove",
"flag": "starred",
"messages": [63],
"message_details":
{
"63":
{
"type": "stream",
"stream_id": 22,
"topic": "lunch",
},
},
"all": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to users in an organization when a [user group](/help/user-groups) is created.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add
group:
$ref: "#/components/schemas/UserGroup"
example:
{
"type": "user_group",
"op": "add",
"group":
{
"name": "backend",
"members": [12],
"description": "Backend team",
"id": 2,
"is_system_group": false,
"can_mention_group": 11,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization
when a property of a user group is changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- update
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
data:
type: object
additionalProperties: false
description: |
Dictionary containing the changed details of the user group.
properties:
name:
type: string
description: |
The new name of the user group. Only present if the group's name changed.
description:
type: string
description: |
The new description of the group. Only present if the description
changed.
can_mention_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value][setting-values] defining the set of users who
have permission to [mention this user group][mentions]. Only present
if this user group permission setting changed.
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
always the integer form of a [group-setting value][setting-values].
Before Zulip 8.0 (feature level 198), this setting was named
`can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups could be
mentioned only if they were not [system groups][system-groups].
Will be one of the following:
[setting-values]: /api/group-setting-values
[system-groups]: /api/group-setting-values#system-groups
[mentions]: /help/mention-a-user-or-group
example:
{
"type": "user_group",
"op": "update",
"group_id": 2,
"data":
{
"description": "Mention this group to get the security team's attention.",
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when users have been added to a user group.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add_members
group_id:
type: integer
description: |
The ID of the user group with new members.
user_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the users who have been added
to the user group.
example:
{
"type": "user_group",
"op": "add_members",
"group_id": 2,
"user_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when users have been removed from
a user group.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove_members
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
user_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the users who have been removed
from the user group.
example:
{
"type": "user_group",
"op": "remove_members",
"group_id": 2,
"user_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when subgroups have been added to
a user group.
**Changes**: New in Zulip 6.0 (feature level 127).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add_subgroups
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
direct_subgroup_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the subgroups that have been added
to the user group.
**Changes**: New in Zulip 6.0 (feature level 131).
Previously, this was called `subgroup_ids`, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
example:
{
"type": "user_group",
"op": "add_subgroups",
"group_id": 2,
"direct_subgroup_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when subgroups have been removed from
a user group.
**Changes**: New in Zulip 6.0 (feature level 127).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove_subgroups
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
direct_subgroup_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the subgroups that have been
removed from the user group.
**Changes**: New in Zulip 6.0 (feature level 131).
Previously, this was called `subgroup_ids`, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
example:
{
"type": "user_group",
"op": "remove_subgroups",
"group_id": 2,
"direct_subgroup_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a user group has been deleted.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove
group_id:
type: integer
description: |
The ID of the group which has been deleted.
example:
{
"type": "user_group",
"op": "remove",
"group_id": 2,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
set of configured [linkifiers](/help/add-a-custom-linkifier)
for the organization has changed.
Processing this event is important for doing Markdown local echo
correctly.
Clients will not receive this event unless the event queue is
registered with the client capability
`{"linkifier_url_template": true}`.
See [`POST /register`](/api/register-queue#parameter-client_capabilities)
for how client capabilities can be specified.
**Changes**: Before Zulip 7.0 (feature level 176), the
`linkifier_url_template` client capability was not required. The
requirement was added because linkifiers were updated to contain
a URL template instead of a URL format string, which was not a
backwards-compatible change.
New in Zulip 4.0 (feature level 54), replacing the deprecated
`realm_filters` event type.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_linkifiers
realm_linkifiers:
type: array
description: |
An ordered array of dictionaries where each dictionary contains
details about a single linkifier.
Clients should always process linkifiers in the order given;
this is important if the realm has linkifiers with overlapping
patterns. The order can be modified using [`PATCH
/realm/linkifiers`](/api/reorder-linkifiers).
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
that represents the pattern that should be linkified by this linkifier.
url_template:
type: string
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
URL template to be used for linkifying matches.
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
which contained a URL format string.
id:
type: integer
description: |
The ID of the linkifier.
example:
{
"type": "realm_linkifiers",
"realm_linkifiers":
[
{
"pattern": "#(?P<id>[123])",
"url_template": "https://realm.com/my_realm_filter/{id}",
"id": 1,
},
],
"id": 0,
}
- type: object
additionalProperties: false
deprecated: true
description: |
Legacy event type that is no longer sent to clients. Previously, sent
to all users in a Zulip organization when the set of configured
[linkifiers](/help/add-a-custom-linkifier) for the organization was
changed.
**Changes**: Prior to Zulip 7.0 (feature level 176), this event type
was sent to clients.
**Deprecated** in Zulip 4.0 (feature level 54), and replaced by the
`realm_linkifiers` event type, which has a clearer name and format.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_filters
realm_filters:
type: array
items:
type: array
items:
oneOf:
- type: integer
- type: string
description: |
An array of tuples, where each tuple described a linkifier. The first
element of the tuple was a string regex pattern which represented the
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
The second element was the URL format string that the pattern should be
linkified with. A URL format string for the above example would be
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
was the ID of the realm filter.
example:
{
"type": "realm_filters",
"realm_filters": [],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
set of configured [code playgrounds](/help/code-blocks#code-playgrounds)
for the organization has changed.
**Changes**: New in Zulip 4.0 (feature level 49).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_playgrounds
realm_playgrounds:
type: array
description: |
An array of dictionaries where each dictionary contains
data about a single playground entry.
items:
$ref: "#/components/schemas/RealmPlayground"
example:
{
"type": "realm_playgrounds",
"realm_playgrounds":
[
{
"id": 1,
"name": "Python playground",
"pygments_language": "Python",
"url_template": "https://python.example.com",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when
a [custom emoji](/help/custom-emoji) has been updated,
typically when a new emoji has been added or an old one
has been deactivated. The event contains all custom emoji
configured for the organization, not just the updated
custom emoji.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_emoji
op:
type: string
enum:
- update
realm_emoji:
type: object
description: |
An object in which each key describes a realm emoji.
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
example:
{
"type": "realm_emoji",
"op": "update",
"realm_emoji":
{
"2":
{
"id": "2",
"name": "my_emoji",
"source_url": "/user_avatars/2/emoji/images/2.png",
"deactivated": true,
"author_id": 11,
},
"1":
{
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/2/emoji/images/1.png",
"deactivated": false,
"author_id": 11,
},
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- add
realm_domain:
$ref: "#/components/schemas/RealmDomain"
example:
{
"type": "realm_domains",
"op": "add",
"realm_domain":
{
"domain": "zulip.org",
"allow_subdomains": false,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- change
realm_domain:
type: object
additionalProperties: false
description: |
Object containing details of the edited domain.
properties:
domain:
type: string
description: |
The domain whose settings have changed.
allow_subdomains:
type: boolean
description: |
Whether subdomains are allowed for this domain.
example:
{
"type": "realm_domains",
"op": "change",
"realm_domain":
{
"domain": "zulip.org",
"allow_subdomains": true,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- remove
domain:
type: string
description: |
The domain to be removed.
example:
{
"type": "realm_domains",
"op": "remove",
"domain": "zulip.org",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to the user who requested a public
[data export](/help/export-your-organization)
when the status of the data export changes.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_export
exports:
type: array
description: |
An array of dictionaries where each dictionary contains
details about a public data export of the organization.
items:
$ref: "#/components/schemas/RealmExport"
example:
{
"type": "realm_export",
"exports":
[
{
"id": 107,
"export_time": 1594825443.6567969322,
"acting_user_id": 10,
"export_url": null,
"deleted_timestamp": null,
"failed_timestamp": 1594825444.4363360405,
"pending": false,
},
],
"id": 1,
}
- type: object
additionalProperties: false
description: |
Event sent to users who can administer a newly created bot
user. Clients will also receive a `realm_user` event that
contains basic details (but not the API key).
The `realm_user` events are sufficient for clients that
only need to interact with the bot; this `realm_bot` event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- add
bot:
$ref: "#/components/schemas/Bot"
example:
{
"type": "realm_bot",
"op": "add",
"bot":
{
"email": "test-bot@zulip.testserver",
"user_id": 36,
"full_name": "Foo Bot",
"bot_type": 1,
"is_active": true,
"api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
"default_sending_stream": null,
"default_events_register_stream": null,
"default_all_public_streams": false,
"avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
"services": [],
"owner_id": 10,
},
"id": 1,
}
- type: object
description: |
Event sent to users who can administer a bot user when the bot is
configured. Clients may also receive a `realm_user` event that
for changes in public data about the bot (name, etc.).
The `realm_user` events are sufficient for clients that
only need to interact with the bot; this `realm_bot` event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- update
bot:
allOf:
- description: |
Object containing details about the changed bot.
It contains two properties: the user ID of the bot and
the property to be changed. The changed property is one
of the remaining properties listed below.
- $ref: "#/components/schemas/BasicBot"
example:
{
"type": "realm_bot",
"op": "update",
"bot":
{
"user_id": 37,
"services":
[
{
"base_url": "http://hostname.domain2.com",
"interface": 2,
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw",
},
],
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a bot has been deactivated.
**Changes**: Deprecated and no longer sent since Zulip 8.0 (feature level 222).
Previously, this event was sent to all users in a Zulip organization when a
bot was deactivated.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- remove
bot:
type: object
description: |
Object containing details about the deactivated bot.
additionalProperties: false
properties:
user_id:
type: integer
description: |
The user ID of the deactivated bot.
full_name:
type: string
description: |
The full name of the deactivated bot.
example:
{
"type": "realm_bot",
"op": "remove",
"bot":
{"user_id": 35, "full_name": "Foo Bot"},
"id": 1,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a bot has been deactivated.
Note that this is very similar to the bot_remove event
and one of them will be removed soon.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- delete
bot:
type: object
description: |
Object containing details about the deactivated bot.
additionalProperties: false
properties:
user_id:
type: integer
description: |
The user ID of the deactivated bot.
example:
{
"type": "realm_bot",
"op": "delete",
"bot": {"user_id": 35},
"id": 1,
}
- type: object
additionalProperties: false
description: |
The simpler of two possible event types sent to all users
in a Zulip organization when the configuration of the
organization (realm) has changed.
Often individual settings are migrated from this format to
the [realm/update_dict](#realm-update_dict) event format when additional realm
settings are added whose values are coupled to each other
in some way. The specific values supported by this event
type are documented in the [realm/update_dict](#realm-update_dict)
documentation.
A correct client implementation should convert these
events into the corresponding [realm/update_dict](#realm-update_dict)
event and then process that.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- update
property:
type: string
description: |
The name of the property that was changed.
value:
description: |
The new value of the property.
nullable: true
oneOf:
- type: string
- type: boolean
- type: integer
extra_data:
description: |
Object containing extra data related to the changed
property.
type: object
additionalProperties: false
properties:
upload_quota:
type: integer
description: |
Note: Only present if changed property is `plan_type`.
The new upload quota for the Zulip organization.
example:
{
"type": "realm",
"op": "update",
"property": "disallow_disposable_email_addresses",
"value": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
organization (realm) is deactivated. Its main purpose is to
flush active longpolling connections so clients can immediately
show the organization as deactivated.
Clients cannot rely on receiving this event, because they will
no longer be able to authenticate to the Zulip API due to the
deactivation, and thus can miss it if they did not have an active
longpolling connection at the moment of deactivation.
Correct handling of realm deactivations requires that clients
parse authentication errors from GET /events; if that is done
correctly, the client can ignore this event type and rely on its
handling of the `GET /events` request it will do immediately
after processing this batch of events.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- deactivated
realm_id:
type: integer
description: |
The ID of the deactivated realm.
example:
{
"type": "realm",
"op": "deactivated",
"realm_id": 2,
"id": 0,
}
- type: object
description: |
Event sent to all the users whenever the Zulip server restarts.
Specifically, this event is sent whenever the Tornado process
for the user is restarted; in particular, this will always happen
when the Zulip server is upgraded.
Clients should use this event to update their tracking of the
server's capabilities, and to decide if they wish to get a new
event queue after a server upgrade. Clients doing so must
implement a random delay strategy to spread such restarts over 5
minutes or more to avoid creating a synchronized thundering herd
effect.
**Changes**: Removed the `immediate` flag, which was only used by
web clients in development, in Zulip 9.0 (feature level 240).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- restart
zulip_version:
type: string
description: |
The Zulip version number, in the format where this appears
in the [server_settings](/api/get-server-settings) and
[register](/api/register-queue) responses.
**Changes**: New in Zulip 4.0 (feature level 59).
zulip_merge_base:
type: string
description: |
The Zulip merge base number, in the format where this appears
in the [server_settings](/api/get-server-settings) and
[register](/api/register-queue) responses.
**Changes**: New in Zulip 5.0 (feature level 88).
zulip_feature_level:
type: integer
description: |
The [Zulip feature level](/api/changelog) of the server
after the restart.
Clients should use this to update their tracking of the
server's capabilities, and may choose to refetch their state
and create a new event queue when the API feature level has
changed in a way that the client finds significant. Clients
choosing to do so must implement a random delay strategy to
spread such restarts over 5 or more minutes to avoid creating
a synchronized thundering herd effect.
**Changes**: New in Zulip 4.0 (feature level 59).
server_generation:
type: integer
description: |
The timestamp at which the server started.
additionalProperties: false
example:
{
"id": 0,
"server_generation": 1619334181,
"type": "restart",
"zulip_feature_level": 57,
"zulip_version": "5.0-dev-1650-gc3fd37755f",
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
}
- type: object
description: |
An event which signals the official Zulip web/desktop app to update,
by reloading the page and fetching a new queue; this will generally
follow a `restart` event. Clients which do not obtain their code
from the server (e.g. mobile and terminal clients, which store their
code locally) should ignore this event.
Clients choosing to reload the application must implement a random
delay strategy to spread such restarts over 5 or more minutes to
avoid creating a synchronized thundering herd effect.
**Changes**: New in Zulip 9.0 (feature level 240).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- web_reload_client
immediate:
type: boolean
description: |
Whether the client should fetch a new event queue immediately,
rather than using a backoff strategy to avoid thundering herds.
A Zulip development server uses this parameter to reload
clients immediately.
additionalProperties: false
example:
{
"id": 0,
"type": "web_reload_client",
"immediate": true,
}
- type: object
additionalProperties: false
description: |
The more general of two event types that may be used when
sending an event to all users in a Zulip organization when
the configuration of the organization (realm) has changed.
Unlike the simpler [realm/update](#realm-update) event format, this
event type supports multiple properties being changed in a
single event.
**Changes**: In Zulip 7.0 (feature level 163), the realm setting
`email_address_visibility` was removed. It was replaced by a [user
setting](/api/update-settings#parameter-email_address_visibility) with
a [realm user default][user-defaults], with the encoding of different
values preserved. Clients can support all versions by supporting the
current API and treating every user as having the realm's
`email_address_visibility` value.
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- update_dict
property:
type: string
deprecated: true
description: |
Always `"default"`. Present for backwards-compatibility with older
clients that predate the `update_dict` event style.
**Deprecated** and will be removed in a future release.
data:
type: object
description: |
An object containing the properties that have changed.
**Changes**: In Zulip 7.0 (feature level 183), the
`community_topic_editing_limit_seconds` property was removed.
It was documented as potentially returned as a changed property
in this event, but in fact it was only ever returned in the
[`POST /register`](/api/register-queue) response.
Before Zulip 6.0 (feature level 150), on changing any of
`allow_message_editing`, `message_content_edit_limit_seconds`, or
`edit_topic_policy` settings, this object included all the three settings
irrespective of which of these settings were changed. Now, a separate event
is sent for each changed setting.
properties:
add_custom_emoji_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add custom emoji in this organization.
allow_edit_history:
type: boolean
description: |
Whether this organization is configured to allow users to access
[message edit history](/help/view-a-messages-edit-history).
allow_message_editing:
type: boolean
description: |
Whether this organizations [message edit policy](/help/restrict-message-editing-and-deletion)
allows editing the content of messages.
authentication_methods:
type: object
additionalProperties:
$ref: "#/components/schemas/RealmAuthenticationMethod"
description: |
Dictionary of authentication method keys mapped to dictionaries that
describe the properties of the named authentication method for the
organization - its enabled status and availability for use by the
organization.
Clients should use this to implement server-settings UI to change which
methods are enabled for the organization. For authentication UI itself,
clients should use the pre-authentication metadata returned by
[`GET /server_settings`](/api/get-server-settings).
**Changes**: In Zulip 9.0 (feature level 243), the values in this
dictionary were changed. Previously, the values were a simple boolean
indicating whether the backend is enabled or not.
bot_creation_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create bot users in this organization.
create_multiuse_invite_group:
type: integer
description: |
The ID of the [user group](/api/get-user-groups) whose members are
allowed to create [reusable invitation
links](/help/invite-new-users#create-a-reusable-invitation-link)
to the organization.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
`"role:internet"` and `"role:owners"`.
**Changes**: New in Zulip 8.0 (feature level 209).
can_create_public_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create public
channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 264). Previously
`realm_create_public_stream_policy` field used to control the
permission to create public channels.
can_create_private_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create private
channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 266). Previously
`realm_create_private_stream_policy` field used to control the
permission to create private channels.
can_create_web_public_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create web-public
channels in this organization.
This setting can only be set to `"role:moderators"`,
`"role:administrators"`, `"role:owners"` and
`"role:nobody"` system groups.
**Changes**: New in Zulip 10.0 (feature level 280). Previously
`realm_create_web_public_stream_policy` field used to control
the permission to create web-public channels.
can_delete_any_message_group:
allOf:
- description: |
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to delete any message in the organization.
**Changes**: New in Zulip 10.0 (feature level 281). Previously, this
permission was limited to administrators only and was uneditable.
- $ref: "#/components/schemas/GroupSettingValue"
default_code_block_language:
type: string
description: |
The default pygments language code to be used for code blocks in this
organization. If an empty string, no default has been set.
**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant
that both `null` and an empty string could represent that no default was
set for this realm setting in the [`POST /register`](/api/register-queue)
response. The documentation for both that endpoint and this event
incorrectly stated that the only representation for no default language
was `null`. This event in fact uses the empty string to indicate that no
default has been set in all server versions.
default_language:
type: string
description: |
The default language for the organization.
description:
type: string
description: |
The description of the organization, used on login and registration pages.
digest_emails_enabled:
type: boolean
description: |
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
digest_weekday:
type: integer
description: |
The day of the week when the organization will send
its weekly digest email to inactive users.
direct_message_initiator_group:
allOf:
- description: |
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to start a new direct message conversation
involving other non-bot users. Users who are outside this group and attempt
to send the first direct message to a given collection of recipient users
will receive an error, unless all other recipients are bots or the sender.
**Changes**: New in Zulip 9.0 (feature level 270).
Previously, access to send direct messages was controlled by the
`private_message_policy` realm setting, which supported values of
1 (enabled) and 2 (disabled).
- $ref: "#/components/schemas/GroupSettingValue"
direct_message_permission_group:
allOf:
- description: |
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to fully use direct messages. Users outside
this group can only send direct messages to conversations where all the
recipients are in this group, are bots, or are the sender, ensuring that
every direct message conversation will be visible to at least one user in
this group.
**Changes**: New in Zulip 9.0 (feature level 270).
Previously, access to send direct messages was controlled by the
`private_message_policy` realm setting, which supported values of
1 (enabled) and 2 (disabled).
- $ref: "#/components/schemas/GroupSettingValue"
disallow_disposable_email_addresses:
type: boolean
description: |
Whether the organization disallows disposable email
addresses.
edit_topic_policy:
type: integer
description: |
The [policy][permission-level] for which users can edit topics of any message.
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 5 = Everyone
- 6 = Nobody
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 5.0 (feature level 75), replacing the previous
`allow_community_topic_editing` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
email_changes_disabled:
type: boolean
description: |
Whether users are allowed to change their own email address in this
organization. This is typically disabled for organizations that
synchronize accounts from LDAP or a similar corporate database.
emails_restricted_to_domains:
type: boolean
description: |
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
this organization are required to have an email
address in one of the `realm_domains` configured for the organization.
enable_spectator_access:
type: boolean
description: |
Whether web-public channels are enabled in this organization.
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
[server setting][server-settings] is enabled on the Zulip
server. See also the `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 109).
giphy_rating:
type: integer
description: |
Maximum rating of the GIFs that will be retrieved from GIPHY.
**Changes**: New in Zulip 4.0 (feature level 55).
icon_source:
type: string
description: |
String indicating whether the organization's
[profile icon](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the organization's icon.
- "G" means generated by Gravatar (the default).
- "U" means uploaded by an organization administrator.
icon_url:
type: string
description: |
The URL of the organization's [profile icon](/help/create-your-organization-profile).
inline_image_preview:
type: boolean
description: |
Whether this organization has been configured to enable
[previews of linked images](/help/image-video-and-website-previews).
inline_url_embed_preview:
type: boolean
description: |
Whether this organization has been configured to enable
[previews of linked websites](/help/image-video-and-website-previews).
invite_required:
type: boolean
description: |
Whether an invitation is required to join this organization.
invite_to_realm_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can invite other users to join the organization.
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
previous `invite_by_admins_only` boolean.
invite_to_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add other users to channels in this organization.
logo_source:
type: string
description: |
String indicating whether the organization's
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
logo_url:
type: string
description: |
The URL of the organization's wide logo configured in the
[organization profile](/help/create-your-organization-profile).
mandatory_topics:
type: boolean
description: |
Whether [topics are required](/help/require-topics) for messages in this organization.
message_content_allowed_in_email_notifications:
type: boolean
description: |
Whether notification emails in this organization are allowed to
contain Zulip the message content, or simply indicate that a new
message was sent.
message_content_delete_limit_seconds:
type: integer
nullable: true
description: |
Messages sent more than this many seconds ago cannot be deleted
with this organization's
[message deletion policy](/help/restrict-message-editing-and-deletion).
Will not be 0. A `null` value means no limit: messages can be deleted
regardless of how long ago they were sent.
**Changes**: No limit was represented using the
special value `0` before Zulip 5.0 (feature level 100).
message_content_edit_limit_seconds:
type: integer
nullable: true
description: |
Messages sent more than this many seconds ago cannot be edited
with this organization's
[message edit policy](/help/restrict-message-editing-and-deletion).
**Changes**: No limit was represented using the
special value `0` before Zulip 6.0 (feature level 138).
move_messages_within_stream_limit_seconds:
type: integer
nullable: true
description: |
Messages sent more than this many seconds ago cannot be moved within a
channel to another topic by users who have permission to do so based on this
organization's [topic edit policy](/help/restrict-moving-messages). This
setting does not affect moderators and administrators.
Will not be 0. A `null` value means no limit, so message topics can be
edited regardless of how long ago they were sent.
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
limit was always 72 hours for users who were not administrators or
moderators.
move_messages_between_streams_limit_seconds:
type: integer
nullable: true
description: |
Messages sent more than this many seconds ago cannot be moved between
channels by users who have permission to do so based on this organization's
[message move policy](/help/restrict-moving-messages). This setting does
not affect moderators and administrators.
Will not be 0. A `null` value means no limit, so messages can be moved
regardless of how long ago they were sent.
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
no time limit for moving messages between channels for users with permission
to do so.
move_messages_between_streams_policy:
type: integer
description: |
The [policy][permission-level] for which users can move messages from
one channel to another.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 6 = Nobody
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 4.0 (feature level 56).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
name:
type: string
description: |
The name of the organization, used in login pages etc.
name_changes_disabled:
type: boolean
description: |
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their name
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
night_logo_source:
type: string
description: |
String indicating whether the organization's dark theme
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
night_logo_url:
type: string
description: |
The URL of the organization's dark theme wide-format logo configured in the
[organization profile](/help/create-your-organization-profile).
new_stream_announcements_stream_id:
type: integer
description: |
The ID of the channel to which automated messages announcing the
[creation of new channels][new-channel-announce] are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements
**Changes**: In Zulip 9.0 (feature level 241), renamed `notifications_stream_id`
to `new_stream_announcements_stream_id`.
org_type:
type: integer
description: |
The [organization type](/help/organization-type)
for the realm.
- 0 = Unspecified
- 10 = Business
- 20 = Open-source project
- 30 = Education (non-profit)
- 35 = Education (for-profit)
- 40 = Research
- 50 = Event or conference
- 60 = Non-profit (registered)
- 70 = Government
- 80 = Political group
- 90 = Community
- 100 = Personal
- 1000 = Other
**Changes**: New in Zulip 6.0 (feature level 128).
plan_type:
type: integer
description: |
The plan type of the organization.
- 1 = Self-hosted organization (SELF_HOSTED)
- 2 = Zulip Cloud free plan (LIMITED)
- 3 = Zulip Cloud Standard plan (STANDARD)
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
presence_disabled:
type: boolean
description: |
Whether online presence of other users is shown in this
organization.
require_unique_names:
type: boolean
description: |
Indicates whether the organization is configured to require users to have
unique full names. If true, the server will reject attempts to create a
new user, or change the name of an existing user, where doing so would
lead to two users whose names are identical modulo case and unicode
normalization.
**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip
server could not be configured to enforce unique names.
send_welcome_emails:
type: boolean
description: |
Whether or not this organization is configured to send the standard Zulip
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
signup_announcements_stream_id:
type: integer
description: |
The ID of the channel to which automated messages announcing
that [new users have joined the organization][new-user-announce] are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
[new-user-announce]: /help/configure-automated-notices#new-user-announcements
**Changes**: In Zulip 9.0 (feature level 241), renamed
`signup_notifications_stream_id` to `signup_announcements_stream_id`.
zulip_update_announcements_stream_id:
type: integer
description: |
The ID of the channel to which automated messages announcing
new features or other end-user updates about the Zulip software are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
**Changes**: New in Zulip 9.0 (feature level 242).
user_group_edit_policy:
type: integer
description: |
The organization's [policy][permission-level] for
[who can manage user groups][user-group-permissions].
- 1 = All members can create and edit user groups
- 2 = Only organization administrators can create and edit user groups
- 3 = Only [full members][calc-full-member] can create and edit user groups
- 4 = Only organization administrators and moderators can create and edit user groups
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
video_chat_provider:
type: integer
description: |
The configured [video call provider](/help/start-a-call) for the
organization.
- 0 = None
- 1 = Jitsi Meet
- 3 = Zoom
- 4 = BigBlueButton
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
to disable video call UI.
jitsi_server_url:
type: string
nullable: true
description: |
The URL of the custom Jitsi Meet server configured in this organization's
settings.
`null`, the default, means that the organization is using the should use the
server-level configuration, `server_jitsi_server_url`.
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only
available as a server-level configuration, and required a server restart to
change.
waiting_period_threshold:
type: integer
description: |
Members whose accounts have been created at least this many days ago
will be treated as [full members][calc-full-member]
for the purpose of settings that restrict access to new members.
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
want_advertise_in_communities_directory:
type: boolean
description: |
Whether the organization has given permission to be advertised in the
Zulip [communities directory](/help/communities-directory).
**Changes**: New in Zulip 6.0 (feature level 129).
wildcard_mention_policy:
type: integer
description: |
The [policy][permission-level] for who can use wildcard mentions in
large channels.
- 1 = Any user can use wildcard mentions in large channels.
- 2 = Only members can use wildcard mentions in large channels.
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.
- 5 = Only organization administrators can use wildcard mentions in large channels.
- 6 = Nobody can use wildcard mentions in large channels.
- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.
All users will receive a warning/reminder when using
mentions in large channels, even when permitted to do so.
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
Zulip 4.0 (feature level 62). Channel administrators option removed in
Zulip 6.0 (feature level 133).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
enable_read_receipts:
type: boolean
description: |
Whether read receipts is enabled in the organization or not.
If disabled, read receipt data will be unavailable to clients, regardless
of individual users' personal read receipt settings. See also the
`send_read_receipts` setting within `realm_user_settings_defaults`.
**Changes**: New in Zulip 6.0 (feature level 137).
enable_guest_user_indicator:
type: boolean
description: |
Whether clients should display "(guest)" after the names of
guest users to prominently highlight their status.
**Changes**: New in Zulip 8.0 (feature level 216).
can_access_all_users_group:
type: integer
description: |
The ID of the [user group](/api/get-user-groups) whose members
are allowed to access all users in the organization.
This setting can currently only be set to `"role:everyone"`
system group.
**Changes**: New in Zulip 8.0 (feature level 225).
push_notifications_enabled:
type: boolean
description: |
Whether push notifications are enabled for this organization. Typically
`true` for Zulip Cloud and self-hosted realms that have a valid
registration for the [Mobile push notifications
service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),
and `false` for self-hosted servers that do not.
**Changes**: New in Zulip 8.0 (feature level 231).
Previously, this value was never updated via events.
push_notifications_enabled_end_timestamp:
type: integer
nullable: true
description: |
If the server expects the realm's push notifications access to end at a
definite time in the future, the time at which this is expected to happen.
Mobile clients should use this field to display warnings to users when the
indicated timestamp is near.
**Changes**: New in Zulip 8.0 (feature level 231).
additionalProperties: false
example:
{
"type": "realm",
"op": "update_dict",
"property": "default",
"data":
{"message_content_edit_limit_seconds": 600},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
[default settings for new users][new-user-defaults]
of the organization (realm) have changed.
[new-user-defaults]: /help/configure-default-new-user-settings
See [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)
for details on possible properties.
**Changes**: New in Zulip 5.0 (feature level 95).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user_settings_defaults
op:
type: string
enum:
- update
property:
type: string
description: |
The name of the property that was changed.
value:
description: |
The new value of the property.
oneOf:
- type: boolean
- type: integer
- type: string
example:
{
"type": "realm_user_settings_defaults",
"op": "update",
"property": "left_side_userlist",
"value": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event containing details of newly created drafts.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- add
drafts:
type: array
description: |
An array containing objects for the newly created drafts.
items:
$ref: "#/components/schemas/Draft"
example:
{
"type": "drafts",
"op": "add",
"drafts":
[
{
"id": 17,
"type": "private",
"to": [6],
"topic": "",
"content": "Hello there!",
"timestamp": 15954790200,
},
],
}
- type: object
additionalProperties: false
description: |
Event containing details for an edited draft.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- update
draft:
$ref: "#/components/schemas/Draft"
example:
{
"type": "drafts",
"op": "update",
"draft":
{
"id": 17,
"type": "private",
"to": [6, 7, 8, 9, 10],
"topic": "",
"content": "Hello everyone!",
"timestamp": 15954790200,
},
}
- type: object
additionalProperties: false
description: |
Event containing the ID of a deleted draft.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- remove
draft_id:
type: integer
description: |
The ID of the draft that was just deleted.
example:
{
"type": "drafts",
"op": "remove",
"draft_id": 17,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when scheduled messages
are created.
**Changes**: New in Zulip 7.0 (feature level 179).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- scheduled_messages
op:
type: string
enum:
- add
scheduled_messages:
type: array
description: |
An array of objects containing details of the newly created
scheduled messages.
items:
$ref: "#/components/schemas/ScheduledMessage"
example:
{
"type": "scheduled_messages",
"op": "add",
"scheduled_messages":
[
{
"scheduled_message_id": 17,
"type": "private",
"to": [6],
"content": "Hello there!",
"rendered_content": "<p>Hello there!</p>",
"scheduled_delivery_timestamp": 1681662420,
"failed": false,
},
],
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when a scheduled message
is edited.
**Changes**: New in Zulip 7.0 (feature level 179).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- scheduled_messages
op:
type: string
enum:
- update
scheduled_message:
$ref: "#/components/schemas/ScheduledMessage"
example:
{
"type": "scheduled_messages",
"op": "update",
"scheduled_message":
{
"scheduled_message_id": 17,
"type": "private",
"to": [6],
"content": "Hello there!",
"rendered_content": "<p>Hello there!</p>",
"scheduled_delivery_timestamp": 1681662420,
"failed": false,
},
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when a scheduled message
is deleted.
**Changes**: New in Zulip 7.0 (feature level 179).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- scheduled_messages
op:
type: string
enum:
- remove
scheduled_message_id:
type: integer
description: |
The ID of the scheduled message that was deleted.
example:
{
"type": "scheduled_messages",
"op": "remove",
"scheduled_message_id": 17,
}
queue_id:
type: string
description: |
The ID of the registered queue.
example:
{
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
"events":
[
{
"id": 0,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "I come not, friends, to steal away your hearts.",
"content_type": "text/x-markdown",
"display_recipient": "Denmark",
"id": 12345678,
"recipient_id": 12314,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"topic_links": [],
"timestamp": 1375978403,
"type": "stream",
},
"type": "message",
},
{
"id": 1,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "With mirth and laughter let old wrinkles come.",
"content_type": "text/x-markdown",
"display_recipient":
[
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572,
},
],
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"subject": "",
"topic_links": [],
"timestamp": 1375978404,
"type": "private",
},
"type": "message",
},
],
"msg": "",
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/BadEventQueueIdError"
- description: |
#### BAD_EVENT_QUEUE_ID errors
This error occurs if the target event queue has been garbage collected.
A compliant client will handle this error by re-initializing itself
(e.g. a Zulip web app browser window will reload in this case).
See [the /register endpoint docs](/api/register-queue) for details on how to
handle these correctly.
The following is the error response in such case:
delete:
operationId: delete-queue
summary: Delete an event queue
tags: ["real_time_events"]
description: |
Delete a previously registered queue.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
queue_id:
description: |
The ID of an event queue that was previously registered via
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
type: string
example: fb67bf8a-c031-47cc-84cf-ed80accacda8
required:
- queue_id
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/BadEventQueueIdError"
- description: |
A typical JSON response for when the `queue_id` is non-existent or the
associated queue has already been deleted:
/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:
/mark_all_as_read:
post:
deprecated: true
operationId: mark-all-as-read
summary: Mark all messages as read
tags: ["messages"]
description: |
Marks all of the current user's unread messages as read.
Because this endpoint marks messages as read in batches, it is possible
for the request to time out after only marking some messages as read.
When this happens, the `complete` boolean field in the success response
will be `false`. Clients should repeat the request when handling such a
response. If all messages were marked as read, then the success response
will return `"complete": true`.
**Changes**: Deprecated; clients should use the [update personal message
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
as this endpoint will be removed in a future release.
Before Zulip 8.0 (feature level 211), if the server's
processing was interrupted by a timeout, but some messages were marked
as read, then it would return `"result": "partially_completed"`, along
with a `code` field for an error string, in the success response to
indicate that there was a timeout and that the client should repeat the
request.
Before Zulip 6.0 (feature level 153), this request did a single atomic
operation, which could time out with 10,000s of unread messages to mark
as read. As of this feature level, messages are marked as read in
batches, starting with the newest messages, so that progress is made
even if the request times out. And, instead of returning an error when
the request times out and some messages have been marked as read, a
success response with `"result": "partially_completed"` is returned.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- complete
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
complete:
type: boolean
description: |
Whether all unread messages were marked as read.
Will be `false` if the request successfully marked
some, but not all, messages as read.
example: {"msg": "", "result": "success", "complete": true}
/mark_stream_as_read:
post:
deprecated: true
operationId: mark-stream-as-read
summary: Mark messages in a channel as read
tags: ["messages"]
description: |
Mark all the unread messages in a channel as read.
**Changes**: Deprecated; clients should use the [update personal message
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
as this endpoint will be removed in a future release.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: |
The ID of the channel to access.
type: integer
example: 43
required:
- stream_id
encoding:
stream_id:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/mark_topic_as_read:
post:
deprecated: true
operationId: mark-topic-as-read
summary: Mark messages in a topic as read
tags: ["messages"]
description: |
Mark all the unread messages in a topic as read.
**Changes**: Deprecated; clients should use the [update personal message
flags for narrow](/api/update-message-flags-for-narrow) endpoint instead
as this endpoint will be removed in a future release.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: |
The ID of the channel to access.
type: integer
example: 43
topic_name:
description: |
The name of the topic whose messages should be marked as read.
type: string
example: new coffee machine
required:
- stream_id
- topic_name
encoding:
stream_id:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/attachments:
get:
operationId: get-attachments
summary: Get attachments
tags: ["users"]
description: |
Fetch metadata on files uploaded by the requesting user.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
attachments:
type: array
description: |
A list of `attachment` objects, each containing
details about a file uploaded by the user.
items:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by users in the organization,
in bytes.
example:
{
"result": "success",
"msg": "",
"attachments":
[
{
"id": 1,
"name": "166050.jpg",
"path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
"size": 571946,
"create_time": 1588145417000,
"messages":
[
{"id": 102, "date_sent": 1588145424000},
{"id": 103, "date_sent": 1588145448000},
],
},
],
"upload_space_used": 571946,
}
/attachments/{attachment_id}:
delete:
operationId: remove-attachment
summary: Delete an attachment
tags: ["users"]
description: |
Delete an uploaded file given its attachment ID.
Note that uploaded files that have been referenced in at least
one message are automatically deleted once the last message
containing a link to them is deleted (whether directly or via
a [message retention policy](/help/message-retention-policy)).
Uploaded files that are never used in a message are
automatically deleted a few weeks after being uploaded.
Attachment IDs can be contained from [GET /attachments](/api/get-attachments).
parameters:
- name: attachment_id
in: path
description: |
The ID of the attachment to be deleted.
schema:
type: integer
example: 1
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid attachment",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the `attachment_id` is invalid
"401":
description: Error.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "UNAUTHORIZED",
"result": "error",
"msg": "Not logged in: API authentication or user session required",
}
description: |
A typical failed JSON response for when the user is not logged in:
/drafts:
get:
operationId: get-drafts
tags: ["drafts"]
summary: Get drafts
description: |
Fetch all drafts for the current user.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
count:
type: integer
description: |
The number of drafts the user currently has. Also the
number of drafts returned under "drafts".
example: 3
drafts:
type: array
description: |
Returns all of the current user's drafts, in order of last edit time
(with the most recently edited draft appearing first).
items:
$ref: "#/components/schemas/Draft"
example:
{
"result": "success",
"msg": "",
"count": 3,
"drafts":
[
{
"id": 1,
"type": "stream",
"to": [3],
"topic": "sync drafts",
"content": "Let's add backend support for syncing drafts.",
"timestamp": 1595479019,
},
{
"id": 2,
"type": "private",
"to": [4],
"topic": "",
"content": "What if we made it possible to sync drafts in Zulip?",
"timestamp": 1595479019,
},
{
"id": 3,
"type": "private",
"to": [4, 10],
"topic": "",
"content": "What if we made it possible to sync drafts in Zulip?",
"timestamp": 1595479019,
},
],
}
post:
operationId: create-drafts
tags: ["drafts"]
summary: Create drafts
description: |
Create one or more drafts on the server. These drafts will be automatically
synchronized to other clients via `drafts` events.
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
drafts:
description: |
A JSON-encoded list of containing new draft objects.
type: array
items:
$ref: "#/components/schemas/Draft"
example:
[
{
"type": "stream",
"to": [1],
"topic": "questions",
"content": "What are the contribution guidelines for this project?",
"timestamp": 1595479019,
},
]
encoding:
drafts:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
ids:
type: array
description: |
An array of the IDs for the drafts that were just created in the same
order as they were submitted.
items:
type: integer
example: {"result": "success", "msg": "", "ids": [1, 2, 3]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
JSON response for when a draft targeted towards a channel does not specify
exactly one channel ID:
example:
{
"code": "BAD_REQUEST",
"msg": "Must specify exactly 1 channel ID for channel messages",
"result": "error",
}
/drafts/{draft_id}:
patch:
operationId: edit-draft
tags: ["drafts"]
summary: Edit a draft
description: |
Edit a draft on the server. The edit will be automatically
synchronized to other clients via `drafts` events.
parameters:
- name: draft_id
in: path
schema:
type: integer
description: |
The ID of the draft to be edited.
required: true
example: 2
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
draft:
allOf:
- $ref: "#/components/schemas/Draft"
- description: |
A JSON-encoded object containing a replacement draft object for this ID.
example:
{
"type": "stream",
"to": [1],
"topic": "questions",
"content": "how tough is a Lamy Safari?",
"timestamp": 1595479019,
}
required:
- draft
encoding:
draft:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when no draft exists with
the provided ID:
example:
{
"code": "BAD_REQUEST",
"result": "error",
"msg": "Draft does not exist",
}
delete:
operationId: delete-draft
tags: ["drafts"]
summary: Delete a draft
description: |
Delete a single draft from the server. The deletion will be automatically
synchronized to other clients via a `drafts` event.
parameters:
- name: draft_id
in: path
schema:
type: integer
description: |
The ID of the draft you want to delete.
required: true
example: 1
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when no draft exists with
the provided ID:
example:
{
"code": "BAD_REQUEST",
"result": "error",
"msg": "Draft does not exist",
}
/scheduled_messages:
get:
operationId: get-scheduled-messages
tags: ["scheduled_messages"]
summary: Get scheduled messages
description: |
Fetch all [scheduled messages](/help/schedule-a-message) for
the current user.
Scheduled messages are messages the user has scheduled to be
sent in the future via the send later feature.
**Changes**: New in Zulip 7.0 (feature level 173).
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
scheduled_messages:
type: array
description: |
Returns all of the current user's undelivered scheduled
messages, ordered by `scheduled_delivery_timestamp`
(ascending).
items:
$ref: "#/components/schemas/ScheduledMessage"
example:
{
"result": "success",
"msg": "",
"scheduled_messages":
[
{
"scheduled_message_id": 27,
"to": 14,
"type": "stream",
"content": "Hi",
"rendered_content": "<p>Hi</p>",
"topic": "Introduction",
"scheduled_delivery_timestamp": 1681662420,
"failed": false,
},
],
}
post:
operationId: create-scheduled-message
tags: ["scheduled_messages"]
summary: Create a scheduled message
description: |
Create a new [scheduled message](/help/schedule-a-message).
**Changes**: In Zulip 7.0 (feature level 184), moved support for
[editing a scheduled message](/api/update-scheduled-message) to a
separate API endpoint, which removed the `scheduled_message_id`
parameter from this endpoint.
New in Zulip 7.0 (feature level 179).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: |
The type of scheduled message to be sent. `"direct"` for a direct
message and `"stream"` or `"channel"` for a channel message.
Note that, while `"private"` is supported for scheduling direct
messages, clients are encouraged to use to the modern convention of
`"direct"` to indicate this message type, because support for
`"private"` may eventually be removed.
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
an additional value for this parameter to indicate the type of a channel
message.
type: string
enum:
- direct
- channel
- stream
- private
example: direct
to:
description: |
The scheduled message's tentative target audience.
For channel messages, the integer ID of the channel.
For direct messages, a list containing integer user IDs.
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example: [9, 10]
content:
$ref: "#/components/schemas/RequiredContent"
topic:
description: |
The topic of the message. Only required for channel messages
(`"type": "stream"` or `"type": "channel"`), ignored otherwise.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
type: string
example: Castle
scheduled_delivery_timestamp:
type: integer
description: |
The UNIX timestamp for when the message will be sent,
in UTC seconds.
example: 3165826990
read_by_sender:
type: boolean
description: |
Whether the message should be initially marked read by its
sender. If unspecified, the server uses a heuristic based
on the client name and the recipient.
**Changes**: New in Zulip 8.0 (feature level 236).
example: true
required:
- type
- to
- content
- scheduled_delivery_timestamp
encoding:
to:
contentType: application/json
scheduled_delivery_timestamp:
contentType: application/json
read_by_sender:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
scheduled_message_id:
type: integer
description: |
The unique ID of the scheduled message.
This is different from the unique ID that the message will have
after it is sent.
example:
{
"msg": "",
"scheduled_message_id": 42,
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/NonExistingChannelIdError"
- description: |
A typical failed JSON response for when a channel message is scheduled
to be sent to a channel that does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user ID 10",
"result": "error",
}
description: |
A typical failed JSON response for when a direct message is scheduled
to be sent to a user that does not exist:
/scheduled_messages/{scheduled_message_id}:
patch:
operationId: update-scheduled-message
tags: ["scheduled_messages"]
summary: Edit a scheduled message
description: |
Edit an existing [scheduled message](/help/schedule-a-message).
**Changes**: New in Zulip 7.0 (feature level 184).
parameters:
- name: scheduled_message_id
in: path
schema:
type: integer
description: |
The ID of the scheduled message to update.
This is different from the unique ID that the message would have
after being sent.
required: true
example: 2
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: |
The type of scheduled message to be sent. `"direct"` for a direct
message and `"stream"` or `"channel"` for a channel message.
When updating the type of the scheduled message, the `to` parameter
is required. And, if updating the type of the scheduled message to
`"stream"`/`"channel"`, then the `topic` parameter is also required.
Note that, while `"private"` is supported for scheduling direct
messages, clients are encouraged to use to the modern convention of
`"direct"` to indicate this message type, because support for
`"private"` may eventually be removed.
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
an additional value for this parameter to indicate the type of a channel
message.
type: string
enum:
- direct
- channel
- stream
- private
example: stream
to:
description: |
The scheduled message's tentative target audience.
For channel messages, the integer ID of the channel.
For direct messages, a list containing integer user IDs.
Required when updating the `type` of the scheduled message.
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example: 11
content:
description: |
The updated content of the scheduled message.
Clients should use the `max_message_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum message size.
type: string
example: Hello
topic:
description: |
The updated topic of the scheduled message.
Required when updating the `type` of the scheduled message to
`"stream"` or `"channel"`. Ignored when the existing or updated
`type` of the scheduled message is `"direct"` (or `"private"`).
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
type: string
example: Castle
scheduled_delivery_timestamp:
type: integer
description: |
The UNIX timestamp for when the message will be sent,
in UTC seconds.
Required when updating a scheduled message that the server
has already tried and failed to send. This state is indicated
with `"failed": true` in `scheduled_messages` objects; see
response description at
[`GET /scheduled_messages`](/api/get-scheduled-messages#response).
example: 3165826990
encoding:
to:
contentType: application/json
scheduled_delivery_timestamp:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/NonExistingChannelIdError"
- description: |
A typical failed JSON response for when a channel message is scheduled
to be sent to a channel that does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user ID 10",
"result": "error",
}
description: |
A typical failed JSON response for when a direct message is scheduled
to be sent to a user that does not exist:
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when no scheduled message exists
with the provided ID:
example:
{
"code": "BAD_REQUEST",
"result": "error",
"msg": "Scheduled message does not exist",
}
delete:
operationId: delete-scheduled-message
tags: ["scheduled_messages"]
summary: Delete a scheduled message
description: |
Delete, and therefore cancel sending, a previously [scheduled
message](/help/schedule-a-message).
**Changes**: New in Zulip 7.0 (feature level 173).
parameters:
- name: scheduled_message_id
in: path
schema:
type: integer
description: |
The ID of the scheduled message to delete.
This is different from the unique ID that the message would have
after being sent.
required: true
example: 1
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when no scheduled message exists
with the provided ID:
example:
{
"code": "BAD_REQUEST",
"result": "error",
"msg": "Scheduled message 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:
/messages:
get:
operationId: get-messages
summary: Get messages
tags: ["messages"]
description: |
Fetch user's message history from a Zulip server.
This endpoint is the primary way to fetch a user's message history
from a Zulip server. It is useful both for Zulip clients (e.g. the
web, desktop, mobile, and terminal clients) as well as bots, API
clients, backup scripts, etc.
Note that a user's message history does not contain messages sent to
channels before they [subscribe](/api/subscribe), and newly created
bot users are not usually subscribed to any channels.
By specifying a [narrow filter](/api/get-messages#parameter-narrow),
you can use this endpoint to fetch the messages matching any search
query that is supported by Zulip's powerful full-text search backend.
In either case, you specify an `anchor` message (or ask the server to
calculate the first unread message for you and use that as the
anchor), as well as a number of messages before and after the anchor
message. The server returns those messages, sorted by message ID, as
well as some metadata that makes it easy for a client to determine
whether there are more messages matching the query that were not
returned due to the `num_before` and `num_after` limits.
We recommend setting `num_before` and `num_after` to no more than 1000, to
avoid generating very large HTTP responses. A maximum of 5000 messages
can be obtained per request; attempting to exceed this will result in an
error.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- client_gravatar
- apply_markdown
- use_first_unread_anchor
- include_anchor
parameters:
- name: anchor
in: query
description: |
Integer message ID to anchor fetching of new messages. Supports special
string values for when the client wants the server to compute the anchor
to use:
- `newest`: The most recent message.
- `oldest`: The oldest message.
- `first_unread`: The oldest unread message matching the
query, if any; otherwise, the most recent message.
**Changes**: String values are new in Zulip 3.0 (feature level 1). The
`first_unread` functionality was supported in Zulip 2.1.x
and older by not sending `anchor` and using `use_first_unread_anchor`.
In Zulip 2.1.x and older, `oldest` can be emulated with
`"anchor": 0`, and `newest` with `"anchor": 10000000000000000`
(that specific large value works around a bug in Zulip
2.1.x and older in the `found_newest` return value).
schema:
$ref: "#/components/schemas/Anchor"
example: "43"
- name: include_anchor
in: query
description: |
Whether a message with the specified ID matching the narrow
should be included.
**Changes**: New in Zulip 6.0 (feature level 155).
schema:
type: boolean
default: true
example: false
- name: num_before
in: query
description: |
The number of messages with IDs less than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 4
required: true
- name: num_after
in: query
description: |
The number of messages with IDs greater than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 8
required: true
- name: narrow
in: query
description: |
The narrow where you want to fetch the messages from. See how to
[construct a narrow](/api/construct-narrow).
Note that many narrows, including all that lack a `channel`, `channels`,
`stream`, or `streams` operator, search the user's personal message
history. See [searching shared
history](/help/search-for-messages#searching-shared-history)
for details.
For example, if you would like to fetch messages from all public channels instead
of only the user's message history, then a specific narrow for
messages sent to all public channels can be used:
`{"operator": "channels", "operand": "public"}`.
Newly created bot users are not usually subscribed to any
channels, so bots using this API should either be
subscribed to appropriate channels or use a shared history
search narrow with this endpoint.
**Changes**: See [changes section](/api/construct-narrow#changes)
of search/narrow filter documentation.
content:
application/json:
schema:
type: array
items:
oneOf:
- type: object
required:
- operator
- operand
additionalProperties: false
properties:
operator:
type: string
operand:
oneOf:
- type: string
- type: integer
- type: array
items:
type: integer
negated:
type: boolean
- type: array
items:
type: string
minItems: 2
maxItems: 2
default: []
example: [{"operand": "Denmark", "operator": "channel"}]
- $ref: "#/components/parameters/ClientGravatar"
- name: apply_markdown
in: query
description: |
If `true`, message content is returned in the rendered HTML
format. If `false`, message content is returned in the raw
Markdown-format text that user entered.
schema:
type: boolean
default: true
example: false
- name: use_first_unread_anchor
in: query
deprecated: true
description: |
Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older.
Whether to use the (computed by the server) first unread message
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by
`"anchor": "first_unread"`.
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: {}
anchor:
type: integer
description: |
The same `anchor` specified in the request (or the computed one, if
`use_first_unread_anchor` is `true`).
found_newest:
type: boolean
description: |
Whether the server promises that the `messages` list includes the very
newest messages matching the narrow (used by clients that paginate their
requests to decide whether there may be more messages to fetch).
found_oldest:
type: boolean
description: |
Whether the server promises that the `messages` list includes the very
oldest messages matching the narrow (used by clients that paginate their
requests to decide whether there may be more messages to fetch).
found_anchor:
type: boolean
description: |
Whether the anchor message is included in the
response. If the message with the ID specified
in the request does not exist, did not match
the narrow, or was excluded via
`"include_anchor": false`, this will be false.
history_limited:
type: boolean
description: |
Whether the message history was limited due to
plan restrictions. This flag is set to `true`
only when the oldest messages(`found_oldest`)
matching the narrow is fetched.
messages:
type: array
description: |
An array of `message` objects.
**Changes**: In Zulip 3.1 (feature level 26), the
`sender_short_name` field was removed from message
objects.
items:
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
flag was deprecated in favor of the `stream_wildcard_mentioned` and
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
for backwards compatibility with older clients and equals
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
supporting older server versions should treat this field as a previous
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
were not available prior to this feature level.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
match_content:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML content of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
match_subject:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML-escaped topic of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
example:
{
"anchor": 21,
"found_newest": true,
"found_anchor": true,
"result": "success",
"msg": "",
"messages":
[
{
"subject": "",
"sender_realm_str": "zulip",
"type": "private",
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
"flags": ["read"],
"id": 16,
"display_recipient":
[
{
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
},
{
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago",
},
{
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest",
},
],
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
{
"subject": "Verona3",
"stream_id": 5,
"sender_realm_str": "zulip",
"type": "stream",
"content": "<p>Wait, is this from the frontend js code or backend python code</p>",
"flags": ["read"],
"id": 21,
"display_recipient": "Verona",
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527939746,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 20,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
],
}
post:
operationId: send-message
summary: Send a message
tags: ["messages"]
description: |
Send a [channel message](/help/introduction-to-topics) or a
[direct message](/help/direct-messages).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: |
The type of message to be sent.
`"direct"` for a direct message and `"stream"` or `"channel"` for a
channel message.
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
an additional value for this parameter to request a channel message.
In Zulip 7.0 (feature level 174), `"direct"` was added as
the preferred way to request a direct message, deprecating the original
`"private"`. While `"private"` is still supported for requesting direct
messages, clients are encouraged to use to the modern convention with
servers that support it, because support for `"private"` will eventually
be removed.
type: string
enum:
- direct
- channel
- stream
- private
example: direct
to:
description: |
For channel messages, either the name or integer ID of the channel. For
direct messages, either a list containing integer user IDs or a list
containing string Zulip API email addresses.
**Changes**: Support for using user/channel IDs was added in Zulip 2.0.0.
oneOf:
- type: string
- type: integer
- type: array
items:
type: string
- type: array
items:
type: integer
minLength: 1
example: [9, 10]
content:
$ref: "#/components/schemas/RequiredContent"
topic:
description: |
The topic of the message. Only required for channel messages
(`"type": "stream"` or `"type": "channel"`), ignored otherwise.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
type: string
example: Castle
queue_id:
type: string
description: |
For clients supporting
[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),
the [event queue](/api/register-queue)
ID for the client. If passed, `local_id` is required. If the message is
successfully sent, the server will include `local_id` in the `message` event
that the client with this `queue_id` will receive notifying it of the new message
via [`GET /events`](/api/get-events). This lets the client know unambiguously
that it should replace the locally echoed message, rather than adding this new
message (which would be correct if the user had sent the new message from another
device).
example: "fb67bf8a-c031-47cc-84cf-ed80accacda8"
local_id:
type: string
description: |
For clients supporting local echo, a unique string-format identifier
chosen freely by the client; the server will pass it back to the client without
inspecting it, as described in the `queue_id` description.
example: "100.01"
read_by_sender:
type: boolean
description: |
Whether the message should be initially marked read by its
sender. If unspecified, the server uses a heuristic based
on the client name.
**Changes**: New in Zulip 8.0 (feature level 236).
example: true
required:
- type
- to
- content
encoding:
to:
contentType: application/json
read_by_sender:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- id
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
id:
type: integer
description: |
The unique ID assigned to the sent message.
automatic_new_visibility_policy:
type: integer
enum:
- 2
- 3
description: |
If the message's sender had configured their [visibility policy settings](/help/mute-a-topic)
to potentially automatically follow or unmute topics when sending messages,
and one of these policies did in fact change the user's visibility policy
for the topic where this message was sent, the new value for that user's
visibility policy for the recipient topic.
Only present if the sender's visibility was in fact changed.
The value can be either [unmuted or followed](/api/update-user-topic#parameter-visibility_policy).
Clients will also be notified about the change in policy via a
`user_topic` event as usual. This field is intended to be used by clients
to explicitly inform the user when a topic's visibility policy was changed
automatically due to sending a message.
For example, the Zulip web application uses this field to decide whether
to display a warning or notice suggesting to unmute the topic after
sending a message to a muted channel. Such a notice would be confusing in
the event that the act of sending the message had already resulted in the
user automatically unmuting or following the topic in question.
**Changes**: New in Zulip 8.0 (feature level 218).
example:
{
"msg": "",
"id": 42,
"automatic_new_visibility_policy": 2,
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/NonExistingChannelNameError"
- description: |
A typical failed JSON response for when a channel message is sent to a channel
that does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error",
}
description: |
A typical failed JSON response for when a direct message is sent to a user
that does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "You do not have permission to use channel wildcard mentions in this channel.",
"code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED",
}
description: |
An example JSON error response for when the message was rejected because
of the organization's `wildcard_mention_policy` and large number of
subscribers to the channel.
**Changes**: New in Zulip 8.0 (feature level 229). Previously, this
error returned the `"BAD_REQUEST"` code.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "You do not have permission to use topic wildcard mentions in this topic.",
"code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED",
}
description: |
An example JSON error response for when the message was rejected because
the message contains a topic wildcard mention, but the user doesn't have
permission to use such a mention in this topic due to the
`wildcard_mention_policy` (and large number of participants in this
specific topic).
**Changes**: New in Zulip 8.0 (feature level 229). Previously,
`wildcard_mention_policy` was not enforced for topic mentions.
/messages/{message_id}/history:
get:
operationId: get-message-history
summary: Get a message's edit history
tags: ["messages"]
description: |
Fetch the message edit history of a previously edited message.
Note that edit history may be disabled in some organizations; see the
[Zulip Help Center documentation on editing messages][edit-settings].
[edit-settings]: /help/view-a-messages-edit-history
parameters:
- $ref: "#/components/parameters/MessageId"
x-response-description: |
Please note that the original message's snapshot only contains the fields
`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This
snapshot will be the only one present if the message has never been edited.
Also note that each snapshot object will only contain additional data for the
modified fields for that particular edit (e.g. if only the topic or channel
was edited, `prev_content`, `prev_rendered_content`, and
`content_html_diff` will not appear).
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
message_history:
type: array
items:
type: object
additionalProperties: false
properties:
topic:
type: string
description: |
The topic of the message immediately
after this edit event.
prev_topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately
prior to this edit event.
stream:
type: integer
description: |
Only present if message's channel was edited.
The ID of the channel containing the message
immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
prev_stream:
type: integer
description: |
Only present if message's channel was edited.
The ID of the channel containing the message immediately
prior to this edit event.
**Changes**: New in Zulip 3.0 (feature level 1).
content:
type: string
description: |
The raw Markdown content of the message
immediately after this edit event.
rendered_content:
type: string
description: |
The rendered HTML representation of `content`.
prev_content:
type: string
description: |
Only present if message's content was edited.
The raw Markdown content of the message immediately
prior to this edit event.
prev_rendered_content:
type: string
description: |
Only present if message's content was edited.
The rendered HTML representation of `prev_content`.
user_id:
type: integer
nullable: true
description: |
The ID of the user that made the edit.
Will be `null` only for edit history
events predating March 2017.
Clients can display edit history events where this
is `null` as modified by either the sender (for content
edits) or an unknown user (for topic edits).
content_html_diff:
type: string
description: |
Only present if message's content was edited.
An HTML diff between this version of the message
and the previous one.
timestamp:
type: integer
description: |
The UNIX timestamp for this edit.
description: |
A chronologically sorted, oldest to newest, array
of `snapshot` objects, each one with the values of
the message after the edit.
example:
{
"message_history":
[
{
"content": "Hello!",
"topic": "party at my houz",
"rendered_content": "<p>Hello!</p>",
"timestamp": 1530129122,
"user_id": 5,
},
{
"topic": "party at my house",
"content": "Howdy!",
"prev_content": "Hello!",
"rendered_content": "<p>Howdy!</p>",
"user_id": 5,
"prev_rendered_content": "<p>Hello!</p>",
"content_html_diff": '<div><p><span class="highlight_text_inserted">Howdy!</span></p> <p><span class="highlight_text_deleted">Hello!</span></p></div>',
"prev_topic": "party at my houz",
"timestamp": 1530129134,
},
],
"msg": "",
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist:
/messages/flags:
post:
operationId: update-message-flags
summary: Update personal message flags
tags: ["messages"]
description: |
Add or remove personal message flags like `read` and `starred`
on a collection of message IDs.
See also the endpoint for [updating flags on a range of
messages within a narrow](/api/update-message-flags-for-narrow).
x-parameter-description: |
## Available flags
<div>
<table>
<thead>
<tr>
<th style="width:30%">Flag</th>
<th style="width:70%">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>read</code></td>
<td>
Whether the user has read the message. Messages
start out unread (except for messages the user
themself sent using a non-API client) and can
later be marked as read.
</td>
</tr>
<tr>
<td><code>starred</code></td>
<td>Whether the user has <a href="/help/star-a-message">starred this message</a>.</td>
</tr>
<tr>
<td><code>collapsed</code></td>
<td>Whether the user has <a href="/help/collapse-a-message">collapsed this message</a>.</td>
</tr>
<tr>
<td><code>mentioned</code></td>
<td>
Whether the current user
<a href="/help/mention-a-user-or-group">was mentioned</a>
by this message, either directly or via a user
group. Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a mention of the current user.
</td>
</tr>
<tr>
<td><code>stream_wildcard_mentioned</code></td>
<td>
Whether this message contained a
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-channel">channel wildcard mention</a>
(like @**all**). Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a channel wildcard mention.
<br /><br />
<b>Changes</b>: New in Zulip 8.0 (feature level 224).
</td>
</tr>
<tr>
<td><code>topic_wildcard_mentioned</code></td>
<td>
Whether this message contained a
<a href="/help/mention-a-user-or-group#mention-all-topic-participants">topic wildcard mention</a>
(@**topic**).
Cannot be changed by the user directly, but can change if
the message is edited to add/remove a topic wildcard mention.
<br /><br />
<b>Changes</b>: New in Zulip 8.0 (feature level 224).
</td>
<tr>
<td><code>has_alert_word</code></td>
<td>
Whether the message contains any of the current user's
<a href="/help/dm-mention-alert-notifications#alert-words">configured alert words</a>.
Cannot be changed by the user directly, but
can change if the message is edited to add/remove
one of the current user's alert words.
</td>
</tr>
<tr>
<td><code>historical</code></td>
<td>
Is <code>true</code> for messages that the user did not receive
at the time they were sent but later was added to
the user's history (e.g. because they starred or
reacted to a message sent to a public channel
before they subscribed to that channel). Cannot be
changed by the user directly.
</td>
</tr>
<tr>
<td><code>wildcard_mentioned</code></td>
<td>
Whether this message contained either a
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-channel">channel wildcard mention</a>
(like @**all**) or a
<a href="/help/mention-a-user-or-group#mention-all-topic-participants">topic wildcard mention</a>
(@**topic**). Cannot be changed by the user directly, but can change if
the message is edited to add/remove a channel and/or topic wildcard
mention.
<br /><br />
<b>Changes</b>: Deprecated in Zulip 8.0 (feature level 224), in favor of
the <code>stream_wildcard_mentioned</code> and
<code>topic_wildcard_mentioned</code> flags. The
<code>wildcard_mentioned</code> flag exists for backwards compatibility
with older clients and equals
<code>stream_wildcard_mentioned || topic_wildcard_mentioned</code>.
Clients supporting older server versions should treat this field as a
previous name for the <code>stream_wildcard_mentioned</code> flag as
topic wildcard mentions were not available prior to this feature level.
</td>
</tr>
</tbody>
</table>
</div>
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
messages:
description: |
An array containing the IDs of the target messages.
type: array
items:
type: integer
example: [4, 8, 15]
op:
description: |
Whether to `add` the flag or `remove` it.
type: string
enum:
- add
- remove
example: add
flag:
description: |
The flag that should be added/removed.
type: string
example: read
required:
- messages
- op
- flag
encoding:
messages:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
messages:
type: array
items:
type: integer
description: |
An array with the IDs of the modified messages.
example:
{"msg": "", "messages": [4, 18, 15], "result": "success"}
/messages/flags/narrow:
post:
operationId: update-message-flags-for-narrow
summary: Update personal message flags for narrow
tags: ["messages"]
description: |
Add or remove personal message flags like `read` and `starred`
on a range of messages within a narrow.
See also [the endpoint for updating flags on specific message
IDs](/api/update-message-flags).
**Changes**: New in Zulip 6.0 (feature level 155).
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- include_anchor
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
anchor:
allOf:
- $ref: "#/components/schemas/Anchor"
- description: |
Integer message ID to anchor updating of flags. Supports special
string values for when the client wants the server to compute the anchor
to use:
- `newest`: The most recent message.
- `oldest`: The oldest message.
- `first_unread`: The oldest unread message matching the
query, if any; otherwise, the most recent message.
example: "43"
include_anchor:
description: |
Whether a message with the specified ID matching the narrow
should be included in the update range.
type: boolean
default: true
example: false
num_before:
description: |
Limit the number of messages preceding the anchor in the
update range. The server may decrease this to bound
transaction sizes.
type: integer
minimum: 0
example: 4
num_after:
description: |
Limit the number of messages following the anchor in the
update range. The server may decrease this to bound
transaction sizes.
type: integer
minimum: 0
example: 8
narrow:
description: |
The narrow you want update flags within. See how to
[construct a narrow](/api/construct-narrow).
Note that, when adding the `read` flag to messages, clients should
consider including a narrow with the `is:unread` filter as an
optimization. Including that filter takes advantage of the fact that
the server has a database index for unread messages.
**Changes**: See [changes section](/api/construct-narrow#changes)
of search/narrow filter documentation.
type: array
items:
oneOf:
- type: object
required:
- operator
- operand
additionalProperties: false
properties:
operator:
type: string
operand:
oneOf:
- type: string
- type: integer
- type: array
items:
type: integer
negated:
type: boolean
- type: array
items:
type: string
minItems: 2
maxItems: 2
default: []
example: [{"operand": "Denmark", "operator": "channel"}]
op:
description: |
Whether to `add` the flag or `remove` it.
type: string
enum:
- add
- remove
example: add
flag:
description: |
The flag that should be added/removed. See [available
flags](/api/update-message-flags#available-flags).
type: string
example: read
required:
- anchor
- num_before
- num_after
- narrow
- op
- flag
encoding:
include_anchor:
contentType: application/json
num_before:
contentType: application/json
num_after:
contentType: application/json
narrow:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- processed_count
- updated_count
- first_processed_id
- last_processed_id
- found_oldest
- found_newest
properties:
result: {}
msg: {}
processed_count:
type: integer
description: |
The number of messages that were within the
update range (at most `num_before + 1 +
num_after`).
updated_count:
type: integer
description: |
The number of messages where the flag's
value was changed (at most
`processed_count`).
first_processed_id:
type: integer
nullable: true
description: |
The ID of the oldest message within the
update range, or `null` if the range was
empty.
last_processed_id:
type: integer
nullable: true
description: |
The ID of the newest message within the
update range, or `null` if the range was
empty.
found_oldest:
type: boolean
description: |
Whether the update range reached backward
far enough to include very oldest message
matching the narrow (used by clients doing a
bulk update to decide whether to issue
another request anchored at
`first_processed_id`).
found_newest:
type: boolean
description: |
Whether the update range reached forward far
enough to include very oldest message
matching the narrow (used by clients doing a
bulk update to decide whether to issue
another request anchored at
`last_processed_id`).
example:
{
"result": "success",
"msg": "",
"processed_count": 11,
"updated_count": 8,
"first_processed_id": 35,
"last_processed_id": 55,
"found_oldest": false,
"found_newest": true,
}
/messages/render:
post:
operationId: render-message
summary: Render a message
tags: ["messages"]
description: |
Render a message to HTML.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
content:
$ref: "#/components/schemas/RequiredContent"
required:
- content
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
rendered:
type: string
description: |
The rendered HTML.
example:
{
"msg": "",
"rendered": "<p><strong>foo</strong></p>",
"result": "success",
}
/messages/{message_id}/reactions:
post:
operationId: add-reaction
summary: Add an emoji reaction
tags: ["messages"]
description: |
Add an [emoji reaction](/help/emoji-reactions) to a message.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- emoji_code
- reaction_type
parameters:
- $ref: "#/components/parameters/MessageId"
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
emoji_name:
description: |
The target emoji's human-readable name.
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
type: string
example: "octopus"
emoji_code:
$ref: "#/components/schemas/EmojiCode"
reaction_type:
$ref: "#/components/schemas/ReactionType"
required:
- emoji_name
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid emoji code",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response for when the emoji code is invalid:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Reaction already exists.",
"code": "REACTION_ALREADY_EXISTS",
}
description: |
An example JSON error response for when the reaction already exists.
**Changes**: New in Zulip 8.0 (feature level 193). Previously, this
error returned the `"BAD_REQUEST"` code.
delete:
operationId: remove-reaction
summary: Remove an emoji reaction
tags: ["messages"]
description: |
Remove an [emoji reaction](/help/emoji-reactions) from a message.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- emoji_code
- reaction_type
parameters:
- $ref: "#/components/parameters/MessageId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
emoji_name:
description: |
The target emoji's human-readable name.
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
type: string
example: "octopus"
emoji_code:
$ref: "#/components/schemas/EmojiCode"
reaction_type:
$ref: "#/components/schemas/ReactionType"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid emoji code",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response for when the emoji code is invalid:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Reaction doesn't exist.",
"code": "REACTION_DOES_NOT_EXIST",
}
description: |
An example JSON error response for when the reaction does not exist.
**Changes**: New in Zulip 8.0 (feature level 193). Previously, this
error returned the `"BAD_REQUEST"` code.
/messages/{message_id}/read_receipts:
get:
operationId: get-read-receipts
summary: Get a message's read receipts
tags: ["messages"]
description: |
Returns a list containing the IDs for all users who have
marked the message as read (and whose privacy settings allow
sharing that information).
The list of users IDs will include any bots who have marked
the message as read via the API (providing a way for bots to
indicate whether they have processed a message successfully in
a way that can be easily inspected in a Zulip client). Bots
for which this behavior is not desired may disable the
`send_read_receipts` setting via the API.
It will never contain the message's sender.
**Changes**: New in Zulip 6.0 (feature level 137).
parameters:
- $ref: "#/components/parameters/MessageId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user_ids:
type: array
description: |
An array of IDs of users who have marked the target message as
read and whose read status is available to the current user.
The IDs of users who have disabled sending read receipts
(`"send_read_receipts": false`) will never appear in the response,
nor will the message's sender. Additionally, the IDs of any users
who have been muted by the current user or who have muted the
current user will not be included in the response.
The current user's ID will appear if they have marked the target
message as read.
**Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of
users who have been muted by or have muted the current user were
included in the response.
items:
type: integer
example:
{"msg": "", "result": "success", "user_ids": [3, 7, 9]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
A typical JSON response when attempting to access read receipts for
a message ID that either does not exist or is not accessible to the
current user:
/messages/matches_narrow:
get:
operationId: check-messages-match-narrow
summary: Check if messages match a narrow
tags: ["messages"]
description: |
Check whether a set of messages match a [narrow](/api/construct-narrow).
For many common narrows (e.g. a topic), clients can write an efficient
client-side check to determine whether a newly arrived message belongs
in the view.
This endpoint is designed to allow clients to handle more complex narrows
for which the client does not (or in the case of full-text search, cannot)
implement this check.
The format of the `match_subject` and `match_content` objects is designed
to match those returned by the [`GET /messages`](/api/get-messages#response)
endpoint, so that a client can splice these fields into a `message` object
received from [`GET /events`](/api/get-events#message) and end up with an
extended message object identical to how a [`GET /messages`](/api/get-messages)
request for the current narrow would have returned the message.
parameters:
- name: msg_ids
in: query
description: List of IDs for the messages to check.
content:
application/json:
schema:
type: array
items:
type: integer
example: [31, 32]
required: true
- name: narrow
in: query
description: |
A structure defining the narrow to check against. See how to
[construct a narrow](/api/construct-narrow).
**Changes**: See [changes section](/api/construct-narrow#changes)
of search/narrow filter documentation.
content:
application/json:
schema:
type: array
items:
type: object
example: [{"operator": "has", "operand": "link"}]
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
messages:
type: object
description: |
A dictionary with a key for each queried message that matches the narrow,
with message IDs as keys and search rendering data as values.
additionalProperties:
type: object
additionalProperties: false
properties:
match_content:
type: string
description: |
HTML content of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included, wrapping the matches for the search keywords.
match_subject:
type: string
description: |
HTML-escaped topic of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included wrapping the matches for the search keywords.
description: |
`message_id`: The ID of the message that matches the narrow. No record will be returned
for queried messages that do not match the narrow.
example:
{
"result": "success",
"msg": "",
"messages":
{
"31":
{
"match_content": '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
"match_subject": "test_topic",
},
},
}
/messages/{message_id}:
get:
operationId: get-message
summary: Fetch a single message
tags: ["messages"]
description: |
Given a message ID, return the message object.
Additionally, a `raw_content` field is included. This field is
useful for clients that primarily work with HTML-rendered
messages but might need to occasionally fetch the message's
raw Markdown (e.g. for [view
source](/help/view-the-markdown-source-of-a-message) or
prefilling a message edit textarea).
**Changes**: Before Zulip 5.0 (feature level 120), this
endpoint only returned the `raw_content` field.
parameters:
- $ref: "#/components/parameters/MessageId"
- name: apply_markdown
in: query
description: |
If `true`, message content is returned in the rendered HTML
format. If `false`, message content is returned in the raw
Markdown-format text that user entered.
**Changes**: New in Zulip 5.0 (feature level 120).
schema:
type: boolean
default: true
example: false
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
raw_content:
type: string
deprecated: true
description: |
The raw Markdown content of the message.
**Deprecated** and to be removed once no longer required for
legacy clients. Modern clients should prefer passing
`"apply_markdown": false` to request raw message content.
message:
description: |
An object containing details of the message.
**Changes**: New in Zulip 5.0 (feature level 120).
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
**Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned`
flag was deprecated in favor of the `stream_wildcard_mentioned` and
`topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists
for backwards compatibility with older clients and equals
`stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients
supporting older server versions should treat this field as a previous
name for the `stream_wildcard_mentioned` flag as topic wildcard mentions
were not available prior to this feature level.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
example:
{
"raw_content": "**Don't** forget your towel!",
"result": "success",
"msg": "",
"message":
{
"subject": "",
"sender_realm_str": "zulip",
"type": "private",
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
"flags": ["read"],
"id": 16,
"display_recipient":
[
{
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
},
{
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago",
},
{
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest",
},
],
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist or it
is not visible to the user making the query (e.g. it was a direct message
between two other users):
patch:
operationId: update-message
summary: Edit a message
tags: ["messages"]
description: |
Edit/update the content, topic, or channel of a message.
`{msg_id}` in the above URL should be replaced with the ID of the
message you wish you update.
You can [resolve topics](/help/resolve-a-topic) by editing the
topic to `✔ {original_topic}`.
See [configuring message editing][config-message-editing] for detailed
documentation on when users are allowed to edit message content and
[restricting moving messages][restrict-move-messages] for detailed
documentation on when users are allowed to change a message's topic
and/or channel.
The relevant realm settings in the API that are related to the above
linked documentation on when users are allowed to update messages are:
- `allow_message_editing`
- `edit_topic_policy`
- `move_messages_between_streams_policy`
- `message_content_edit_limit_seconds`
- `move_messages_within_stream_limit_seconds`
- `move_messages_between_streams_limit_seconds`
More details about these realm settings can be found in the
[`POST /register`](/api/register-queue) response or in the documentation
of the [`realm op: update_dict`](/api/get-events#realm-update_dict)
event in [`GET /events`](/api/get-events).
**Changes**: Prior to Zulip 7.0 (feature level 172), anyone could add a
topic to channel messages without a topic, regardless of the organization's
[topic editing permissions](/help/restrict-moving-messages). As of this
feature level, messages without topics have the same restrictions for
topic edits as messages with topics.
Before Zulip 7.0 (feature level 172), by using the `change_all` value for
the `propagate_mode` parameter, users could move messages after the
organization's configured time limits for changing a message's topic or
channel had passed. As of this feature level, the server will [return an
error](/api/update-message#response) with `"code":
"MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"` if users, other than organization
administrators or moderators, try to move messages after these time
limits have passed.
Before Zulip 7.0 (feature level 162), users who were not administrators or
moderators could only edit topics if the target message was sent within the
last 3 days. As of this feature level, that time limit is now controlled by
the realm setting `move_messages_within_stream_limit_seconds`. Also at this
feature level, a similar time limit for moving messages between channels was
added, controlled by the realm setting
`move_messages_between_streams_limit_seconds`. Previously, all users who
had permission to move messages between channels did not have any time limit
restrictions when doing so.
Before Zulip 7.0 (feature level 159), editing channels and topics of messages
was forbidden if the realm setting for `allow_message_editing` was `false`,
regardless of an organization's configuration for the realm settings
`edit_topic_policy` or `move_messages_between_streams_policy`.
Before Zulip 7.0 (feature level 159), message senders were allowed to edit
the topic of their messages indefinitely.
[config-message-editing]: /help/restrict-message-editing-and-deletion
[restrict-move-messages]: /help/restrict-moving-messages
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- stream_id
parameters:
- $ref: "#/components/parameters/MessageId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
topic:
description: |
The topic to move the message(s) to, to request changing the topic.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length
Should only be sent when changing the topic, and will throw an error
if the target message is not a channel message.
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
type: string
example: Castle
propagate_mode:
description: |
Which message(s) should be edited:
- `"change_later"`: The target message and all following messages.
- `"change_one"`: Only the target message.
- `"change_all"`: All messages in this topic.
Only the default value of `"change_one"` is valid when editing
only the content of a message.
This parameter determines both which messages get moved and also whether
clients that are currently narrowed to the topic containing the message
should navigate or adjust their compose box recipient to point to the
post-edit channel/topic.
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
send_notification_to_old_thread:
description: |
Whether to send an automated message to the old topic to
notify users where the messages were moved to.
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
had a default of `true` and was ignored unless the channel was changed.
New in Zulip 3.0 (feature level 9).
type: boolean
default: false
example: true
send_notification_to_new_thread:
description: |
Whether to send an automated message to the new topic to
notify users where the messages came from.
If the move is just [resolving/unresolving a topic](/help/resolve-a-topic),
this parameter will not trigger an additional notification.
**Changes**: Before Zulip 6.0 (feature level 152), this parameter
was ignored unless the channel was changed.
New in Zulip 3.0 (feature level 9).
type: boolean
default: true
example: true
content:
$ref: "#/components/schemas/OptionalContent"
stream_id:
description: |
The channel ID to move the message(s) to, to request moving
messages to another channel.
Should only be sent when changing the channel, and will throw an error
if the target message is not a channel message.
Note that a message's content and channel cannot be changed at the
same time, so sending both `content` and `stream_id` parameters will
throw an error.
**Changes**: New in Zulip 3.0 (feature level 1).
type: integer
example: 43
encoding:
send_notification_to_old_thread:
contentType: application/json
send_notification_to_new_thread:
contentType: application/json
stream_id:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- properties:
msg:
enum:
- Your organization has turned off message editing
- You don't have permission to edit this message
- The time limit for editing this message has past
- Nothing to change
- Topic can't be empty
example:
{
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
"result": "error",
}
description: |
A typical JSON response for when one doesn't have the permission to
edit a particular message:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED",
"first_message_id_allowed_to_move": 123,
"msg": "You only have permission to move the 2/5 most recent messages in this topic.",
"result": "error",
"total_messages_allowed_to_move": 2,
"total_messages_in_topic": 5,
}
description: |
A special failed JSON response (`"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"`)
for when the user has permission to move
the target message, but asked to move all messages in a topic
(`"propagate_mode": "change_all"`) and the user does not have permission
to move the entire topic.
This happens when the topic contains some messages that are older than an
applicable time limit for the requested topic move (see
`move_messages_within_stream_limit_seconds` and/or
`move_messages_between_streams_limit_seconds` in the
[`POST /register`](/api/register-queue) response).
The error response contains data on which portion of this topic the user has
permission to move. `first_message_id_allowed_to_move` is the oldest message
ID in this topic that the user has permission to move.
There are `total_messages_in_topic` in the topic, but the user only has
permission to move the (most recent) `total_messages_allowed_to_move`
messages.
Clients should support this error code with
`"first_message_id_allowed_to_move": null` for forward compatibility
with future server versions that may use this error code with other
propagation modes where the user does not have permission to move any
messages, or where the server did not calculate the total message counts
noted above.
Clients can either only present the error to the user or, if
`first_message_id_allowed_to_move` is not `null`, prompt the user to adjust
their query with the above information.
If clients choose to present a prompt for this error code, they should
recommend the option of cancelling and (manually) asking a moderator to
move the entire topic, since that's often a better experience than
partially moving a topic. This API supports a client that wishes to allow
the user to repeat the request with a `change_later` propagation mode and
a target message ID of `first_message_id_allowed_to_move`, if the user
desires to move only the portion of the topic that they can.
Note that in a channel with [protected history](/help/channel-permissions),
the Zulip security model requires that the above calculations only include
messages the acting user has access to. So in the rare case of a user
attempting to move a topic that started before the user joined a private
channel with protected history, this API endpoint might move only the portion
of a topic that they have access to, without this error or any confirmation
dialog.
**Changes**: New in Zulip 7.0 (feature level 172).
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "You do not have permission to use channel wildcard mentions in this channel.",
"code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED",
}
description: |
An example JSON error response for when the message was rejected because
of the organization's `wildcard_mention_policy` and large number of
subscribers to the channel.
**Changes**: New in Zulip 8.0 (feature level 229). Previously, this
error returned the `"BAD_REQUEST"` code.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "You do not have permission to use topic wildcard mentions in this topic.",
"code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED",
}
description: |
An example JSON error response for when the message was rejected because
the message contains a topic wildcard mention, but the user doesn't have
permission to use such a mention in this topic due to the
`wildcard_mention_policy` (and large number of participants in this
specific topic).
**Changes**: New in Zulip 8.0 (feature level 229). Previously,
`wildcard_mention_policy` was not enforced for topic mentions.
delete:
operationId: delete-message
summary: Delete a message
tags: ["messages"]
description: |
Permanently delete a message.
This API corresponds to the
[delete a message completely][delete-completely] feature documented in
the Zulip Help Center.
[delete-completely]: /help/delete-a-message#delete-a-message-completely
x-requires-administrator: true
parameters:
- $ref: "#/components/parameters/MessageId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
An example JSON response for when the user making the query does not
have permission to delete the message:
example:
{
"code": "BAD_REQUEST",
"msg": "You don't have permission to delete this message",
"result": "error",
}
/user_uploads:
post:
operationId: upload-file
summary: Upload a file
tags: ["messages"]
description: |
Upload a single file and get the corresponding URL.
Initially, only you will be able to access the link. To share the
uploaded file, you'll need to [send a message][send-message]
containing the resulting link. Users who can already access the link
can reshare it with other users by sending additional Zulip messages
containing the link.
[uploaded-files]: /help/manage-your-uploaded-files
[send-message]: /api/send-message
x-parameter-description: |
As described above, the file to upload must be provided in the
request's body.
## Maximum file size
The maximum file size for uploads can be configured by the
administrator of the Zulip server by setting `MAX_FILE_UPLOAD_SIZE`
in the [server's settings][1]. `MAX_FILE_UPLOAD_SIZE` defaults
to 25MB.
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filename:
type: string
format: binary
example: /path/to/file
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
uri:
type: string
deprecated: true
description: |
The URL of the uploaded file. Alias of `url`.
**Changes**: Deprecated in Zulip 9.0 (feature level 272). The term
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
url:
type: string
description: |
The URL of the uploaded file.
**Changes**: New in Zulip 9.0 (feature level 272). Previously,
this property was only available under the legacy `uri` name.
example:
{
"msg": "",
"result": "success",
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
"url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
}
/user_uploads/{realm_id_str}/{filename}:
get:
operationId: get-file-temporary-url
summary: Get public temporary URL
tags: ["messages"]
description: |
Get a temporary URL for access to the file that doesn't require authentication.
**Changes**: New in Zulip 3.0 (feature level 1).
parameters:
- name: realm_id_str
in: path
description: |
The realm ID.
schema:
type: integer
example: 1
required: true
- name: filename
in: path
description: |
Path to the URL.
schema:
type: string
example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
url:
type: string
description: |
A temporary URL that can be used to access the uploaded file
without Zulip's normal API authentication.
example:
{
"msg": "",
"result": "success",
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55",
}
/users:
get:
operationId: get-users
summary: Get all users
tags: ["users"]
description: |
Retrieve details on all users in the organization. Optionally
includes values of [custom profile fields](/help/custom-profile-fields).
You can also [fetch details on a single user](/api/get-user).
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` query parameter as follows:
parameters:
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
members:
type: array
description: |
A list of `user` objects, each containing details about a user in the
organization.
items:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"members":
[
{
"is_active": true,
"email": "AARON@zulip.com",
"delivery_email": null,
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
"bot_type": null,
"timezone": "",
"is_bot": false,
"user_id": 7,
"profile_data": {},
"is_guest": false,
"date_joined": "2019-10-20T07:50:53.728864+00:00",
"full_name": "aaron",
},
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "0"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
"delivery_email": null,
},
{
"bot_owner_id": 11,
"is_guest": false,
"date_joined": "2019-10-20T12:52:17.862053+00:00",
"full_name": "Iago's Bot",
"email": "iago-bot@zulipdev.com",
"delivery_email": "iago-bot@zulipdev.com",
"is_active": true,
"avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"user_id": 23,
"bot_type": 1,
"timezone": "",
"is_bot": true,
},
],
}
post:
operationId: create-user
summary: Create a user
tags: ["users"]
description: |
Create a new user account via the API.
!!! warn ""
**Note**: On Zulip Cloud, this feature is available only for
organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)
or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators
can request the required `can_create_users` permission for a bot or
user by contacting [Zulip Cloud support][support] with an
explanation for why it is needed. Self-hosted installations can
toggle `can_create_users` on an account using the `manage.py
change_user_role` [management command][management-commands].
**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was
available to all organization administrators.
[support]: /help/contact-support
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
x-requires-administrator: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
email:
description: |
The email address of the new user.
type: string
example: username@example.com
password:
description: |
The password of the new user.
type: string
example: abcd1234
full_name:
description: |
The full name of the new user.
type: string
example: New User
required:
- email
- password
- full_name
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user_id:
type: integer
description: |
The ID assigned to the newly created user.
**Changes**: New in Zulip 4.0 (feature level 30).
example: {"msg": "", "result": "success", "user_id": 25}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Email 'newbie@zulip.com' already in use",
"result": "error",
}
description: |
A typical JSON response for when another user with the same
email address already exists in the realm:
/users/{user_id}/reactivate:
post:
operationId: reactivate-user
summary: Reactivate a user
tags: ["users"]
x-requires-administrator: true
description: |
[Reactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
parameters:
- $ref: "#/components/parameters/UserId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/users/{user_id}/status:
get:
operationId: get-user-status
summary: Get a user's status
tags: ["users"]
description: |
Get the [status](/help/status-and-availability) currently set by a
user in the organization.
**Changes**: New in Zulip 9.0 (feature level 262). Previously,
user statuses could only be fetched via the [`POST
/register`](/api/register-queue) endpoint.
parameters:
- $ref: "#/components/parameters/UserId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
status:
allOf:
- description: |
The status set by the user. Note that, if the user doesn't have a status
currently set, then the returned dictionary will be empty as none of the
keys listed below will be present.
- $ref: "#/components/schemas/UserStatus"
example:
{
"result": "success",
"msg": "",
"status":
{
"status_text": "on vacation",
"emoji_name": "car",
"emoji_code": "1f697",
"reaction_type": "unicode_emoji",
},
}
"400":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "No such user",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the user does not exist:
/users/{user_id_or_email}/presence:
get:
operationId: get-user-presence
summary: Get a user's presence
tags: ["users"]
description: |
Get the presence status for a specific user.
This endpoint is most useful for embedding data about a user's
presence status in other sites (e.g. an employee directory). Full
Zulip clients like mobile/desktop apps will want to use the [main
presence endpoint](/api/get-presence), which returns data for all
active users in the organization, instead.
See [Zulip's developer documentation][subsystems-presence]
for details on the data model for presence in Zulip.
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
parameters:
- name: user_id_or_email
in: path
description: |
The ID or Zulip API email address of the user whose presence you want to fetch.
**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported
identifying the user by Zulip API email.
schema:
type: string
example: iago@zulip.com
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
presence:
type: object
description: |
An object containing the presence details for the user.
additionalProperties:
type: object
additionalProperties: false
properties:
timestamp:
type: integer
description: |
When this update was received. If the timestamp
is more than a few minutes in the past, the user is offline.
status:
type: string
description: |
Whether the user had recently interacted with Zulip at the time
of the timestamp.
Will be either `"active"` or `"idle"`
description: |
`{client_name}` or `"aggregated"`: Object containing the details of the user's
presence.
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
contain two keys, `"website"` and `"aggregated"`, with identical data. The
server no longer stores which client submitted presence updates.
Previously, the `{client_name}` keys for these objects were the names of the
different clients where the user was logged in, for example `website` or
`ZulipDesktop`.
example:
{
"presence":
{
"website":
{"timestamp": 1532697622, "status": "active"},
"aggregated":
{"timestamp": 1532697622, "status": "active"},
},
"result": "success",
"msg": "",
}
/users/me:
get:
operationId: get-own-user
summary: Get own user
tags: ["users"]
description: |
Get basic data about the user/bot that requests this endpoint.
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
avatar_url:
type: string
description: |
URL for the requesting user's avatar.
**Changes**: New in Zulip 2.1.0.
example: "x"
avatar_version:
type: integer
description: |
Version for the requesting user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
**Changes**: New in Zulip 3.0 (feature level 10).
example: 1
email:
type: string
description: |
Zulip API email of the requesting user.
example: "iago@zulip.com"
full_name:
type: string
description: |
Full name of the requesting user.
example: "Iago"
is_admin:
type: boolean
description: |
A boolean indicating if the requesting user is an admin.
example: true
is_owner:
type: boolean
description: |
A boolean indicating if the requesting user is
an organization owner.
**Changes**: New in Zulip 3.0 (feature level 8).
example: false
is_billing_admin:
type: boolean
description: |
A boolean indicating if the requesting user is
a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
example: false
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: |
[Organization-level role](/api/roles-and-permissions) of
the requesting user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
**Changes**: New in Zulip 4.0 (feature level 59).
is_guest:
type: boolean
description: |
A boolean indicating if the requesting user is a guest.
**Changes**: New in Zulip 3.0 (feature level 10).
example: false
is_bot:
type: boolean
description: |
A boolean indicating if the requesting user is a bot.
example: false
is_active:
type: boolean
description: |
A boolean specifying whether the requesting user account
has been deactivated.
**Changes**: New in Zulip 3.0 (feature level 10).
example: true
timezone:
type: string
description: |
The time zone of the requesting user.
**Changes**: New in Zulip 3.0 (feature level 10).
example: ""
date_joined:
type: string
description: |
The time the requesting user's account was created.
**Changes**: New in Zulip 3.0 (feature level 10).
example: "2019-10-20T07:50:53.728864+00:00"
max_message_id:
type: integer
deprecated: true
description: |
The integer ID of the last message received by the requesting
user's account.
**Deprecated**. We plan to remove this in favor of recommending
using `GET /messages` with `"anchor": "newest"`.
example: 30
user_id:
type: integer
description: |
The user's ID.
example: 1
delivery_email:
type: string
description: |
The requesting user's real email address.
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
present only when `email_address_visibility` was restricted and the
requesting user had permission to access realm users' emails. As of
this feature level, this field is always present.
profile_data:
$ref: "#/components/schemas/profile_data"
example:
{
"avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1",
"avatar_version": 1,
"email": "iago@zulip.com",
"delivery_email": iago@zulip.com,
"full_name": "Iago",
"is_admin": true,
"is_owner": false,
"role": 200,
"is_guest": false,
"is_billing_admin": false,
"is_bot": false,
"is_active": true,
"timezone": "",
"date_joined": "2019-10-20T07:50:53.728864+00:00",
"max_message_id": 30,
"msg": "",
"result": "success",
"user_id": 5,
"profile_data":
{
"5": {"value": "2000-01-01"},
"4": {"value": "emacs"},
"7": {"value": "[10]"},
"1":
{
"value": "+1-234-567-8901",
"rendered_value": "<p>+1-234-567-8901</p>",
},
"2":
{
"rendered_value": "<p>Betrayer of Othello.</p>",
"value": "Betrayer of Othello.",
},
"8": {"value": "zulip"},
"3":
{
"value": "Apples",
"rendered_value": "<p>Apples</p>",
},
"6":
{
"value": "https://zulip.readthedocs.io/en/latest/",
},
},
}
delete:
operationId: deactivate-own-user
summary: Deactivate own user
tags: ["users"]
description: |
Deactivates the current user's account. See also the administrative endpoint for
[deactivating another user](/api/deactivate-user).
This endpoint is primarily useful to Zulip clients providing a user settings UI.
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
entity:
type: string
description: |
An internationalized string that notes if the current user is the only
organization owner or the only user in the organization.
is_last_owner:
type: boolean
description: |
Whether the current user is the only organization owner (meaning there
are other active users in the organization) or the only active user in the
organization.
required:
- entity
- is_last_owner
example:
{
"code": "CANNOT_DEACTIVATE_LAST_USER",
"msg": "Cannot deactivate the only organization owner",
"result": "error",
"entity": "organization owner",
"is_last_owner": true,
}
description: |
If the current user is the only organization owner or only user in the
organization, their account cannot be deactivated and an error response
will be returned. The `is_last_owner` field in the error response
indicates whether the user is the only owner (`true`) or the only user
(`false`). The `entity` field in the error response is a internationalized
string that notes if the current user is the only organization owner or
the only user.
An example JSON error response when the current user is the only
organization owner in the organization:
/users/me/alert_words:
get:
operationId: get-alert-words
summary: Get all alert words
tags: ["users"]
description: |
Get all of the user's configured [alert words][alert-words].
[alert-words]: /help/dm-mention-alert-notifications#alert-words
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
alert_words:
type: array
description: |
An array of strings, where each string is an alert word (or phrase)
configured by the user.
items:
type: string
example:
{
"result": "success",
"msg": "",
"alert_words": ["natural", "illustrious"],
}
post:
operationId: add-alert-words
summary: Add alert words
tags: ["users"]
description: |
Add words (or phrases) to the user's set of configured [alert words][alert-words].
[alert-words]: /help/dm-mention-alert-notifications#alert-words
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
alert_words:
description: |
An array of strings to be added to the user's set of configured
alert words. Strings already present in the user's set of alert words
already are ignored.
Alert words are case insensitive.
type: array
items:
type: string
example: ["foo", "bar"]
required:
- alert_words
encoding:
alert_words:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
alert_words:
type: array
description: |
An array of strings, where each string is an alert word (or phrase)
configured by the user.
items:
type: string
example:
{
"result": "success",
"msg": "",
"alert_words": ["foo", "bar", "natural", "illustrious"],
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "alert_words[0] is too long (limit: 100 characters)",
"result": "error",
}
description: |
An example JSON response for when a supplied alert word (or phrase)
exceeds the character limit:
delete:
operationId: remove-alert-words
summary: Remove alert words
tags: ["users"]
description: |
Remove words (or phrases) from the user's set of configured [alert words][alert-words].
Alert words are case insensitive.
[alert-words]: /help/dm-mention-alert-notifications#alert-words
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
alert_words:
description: |
An array of strings to be removed from the user's set of configured
alert words. Strings that are not in the user's set of alert words
are ignored.
type: array
items:
type: string
example: ["foo"]
required:
- alert_words
encoding:
alert_words:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
alert_words:
type: array
description: |
An array of strings, where each string is an alert word (or phrase)
configured by the user.
items:
type: string
example:
{
"result": "success",
"msg": "",
"alert_words": ["bar", "natural", "illustrious"],
}
/users/me/presence:
post:
operationId: update-presence
summary: Update your presence
tags: ["users"]
description: |
Update the current user's [presence][availability] and fetch presence data
of other users in the organization.
This endpoint is meant to be used by clients for both:
- Reporting the current user's presence status (`"active"` or `"idle"`)
to the server.
- Obtaining the presence data of all other users in the organization via
regular polling (in parallel with receiving
[`presence` events](/api/get-events#presence)).
Accurate user presence is one of the most expensive parts of any
chat application (in terms of bandwidth and other resources). Therefore,
it is important that clients implementing Zulip's user presence system
use the modern [`last_update_id`](#parameter-last_update_id) protocol to
minimize fetching duplicate user presence data.
See [Zulip's developer documentation][subsystems-presence] for details
on the data model for user presence in Zulip.
The Zulip server is responsible for implementing [invisible mode][invisible],
which disables sharing a user's presence data. Nonetheless, clients
should check the `presence_enabled` field in user objects in order to
display the current user as online or offline based on whether they are
sharing their presence information.
**Changes**: As of Zulip 8.0 (feature level 228), if the
`CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is
`true`, then user presence data in the response is [limited to users
the current user can see/access][limit-visibility].
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
[limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users
[invisible]: /help/status-and-availability#invisible-mode
[availability]: /help/status-and-availability#availability
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
last_update_id:
type: integer
description: |
The identifier that specifies what presence data the client already
has received, which allows the server to only return more recent
user presence data.
This should be set to `-1` during initialization of the client in
order to fetch all user presence data, unless the client is obtaining
initial user presence metadata from the
[`POST /register`](/api/register-queue) endpoint.
In subsequent queries to this endpoint, this value should be set to the
most recent value of `presence_last_update_id` returned by the server
in this endpoint's response, which implements incremental fetching
of user presence data.
When this parameter is passed, the user presence data in the response
will always be in the modern format.
**Changes**: New in Zulip 9.0 (feature level 263). Previously, the
server sent user presence data for all users who had been active in the
last two weeks unconditionally.
example: 5
new_user_input:
type: boolean
description: |
Whether the user has interacted with the client (e.g. moved the mouse,
used the keyboard, etc.) since the previous presence request from this
client.
The server uses data from this parameter to implement certain [usage
statistics](/help/analytics).
User interface clients that might run in the background, without the
user ever interacting with them, should be careful to only pass `true`
if the user has actually interacted with the client in order to avoid
corrupting usage statistics graphs.
example: false
default: false
ping_only:
type: boolean
description: |
Whether the client is sending a ping-only request, meaning it only
wants to update the user's presence `status` on the server.
Otherwise, also requests the server return user presence data for all
users in the organization, which is further specified by the
[`last_update_id`](#parameter-last_update_id) parameter.
example: false
default: false
slim_presence:
type: boolean
description: |
Legacy parameter for configuring the format (modern or legacy) in
which the server will return user presence data for the organization.
Modern clients should use
[`last_update_id`](#parameter-last_update_id), which guarantees that
user presence data will be returned in the modern format, and
should not pass this parameter as `true` unless interacting with an
older server.
Legacy clients that do not yet support `last_update_id` may use the
value of `true` to request the modern format for user presence data.
**Note**: The legacy format for user presence data will be removed
entirely in a future release.
**Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using
the modern `last_update_id` parameter is the recommended way to
request the modern format for user presence data.
New in Zulip 3.0 (no feature level as it was an unstable API at that
point).
example: false
default: false
deprecated: true
status:
type: string
enum:
- idle
- active
description: |
The status of the user on this client.
Clients should report the user as `"active"` on this device if the client
knows that the user is presently using the device (and thus would
potentially see a notification immediately), even if the user
has not directly interacted with the Zulip client.
Otherwise, it should report the user as `"idle"`.
See the related [`new_user_input`](#parameter-new_user_input) parameter
for how a client should report whether the user is actively using the
Zulip client.
example: active
required:
- status
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- result
- msg
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
presence_last_update_id:
type: integer
description: |
The identifier for the latest user presence data returned in
the `presences` data of the response.
If a value was passed for `last_update_id`, then this is
guaranteed to be equal to or greater than that value. If it
is the same value, then that indicates to the client that
there were no updates to previously received user presence
data.
The client should then pass this value as the `last_update_id`
parameter when it next queries this endpoint, in order to only
receive new user presence data and avoid redundantly fetching
already known information.
This will be `-1` if no value was passed for
[`last_update_id`](#parameter-last_update_id) and no user
presence data was returned by the server. This can happen, for
example, if an organization has disabled presence.
**Changes**: New in Zulip 9.0 (feature level 263).
server_timestamp:
type: number
description: |
Only present if `ping_only` is `false`.
The time when the server fetched the `presences` data included
in the response.
presences:
type: object
description: |
Only present if `ping_only` is `false`.
A dictionary where each entry describes the presence details
of a user in the Zulip organization. Entries can be in either
the modern presence format or the legacy presence format.
These entries will be the modern presence format when the
`last_updated_id` parameter is passed, or when the deprecated
`slim_presence` parameter is `true`.
If the deprecated `slim_presence` parameter is `false` and the
`last_updated_id` parameter is omitted, the entries will be in
the legacy presence API format.
**Note**: The legacy presence format should only be used when
interacting with old servers. It will be removed as soon as
doing so is practical.
additionalProperties:
description: |
Will be one of these two formats (modern or legacy) for user
presence data:
oneOf:
- $ref: "#/components/schemas/ModernPresenceFormat"
- type: object
description: |
`{user_email}`: Presence data (legacy format) for the user with
the specified Zulip API email.
additionalProperties:
$ref: "#/components/schemas/LegacyPresenceFormat"
zephyr_mirror_active:
type: boolean
deprecated: true
description: |
Legacy property for a part of the Zephyr mirroring system.
**Deprecated**. Clients should ignore this field.
examples:
modern-presence-format-example:
description: |
Modern presence format:
value:
{
"msg": "",
"presences":
{
"10":
{
"idle_timestamp": 1656958530,
"active_timestamp": 1656958520,
},
},
"result": "success",
"server_timestamp": 1656958539.6287155,
"presence_last_update_id": 1000,
}
legacy-presence-format-example:
description: |
Legacy presence format:
value:
{
"msg": "",
"presences":
{
"user@example.com":
{
"aggregated":
{
"client": "website",
"status": "idle",
"timestamp": 1594825445,
},
"website":
{
"client": "website",
"status": "idle",
"timestamp": 1594825445,
"pushable": false,
},
},
},
"result": "success",
"server_timestamp": 1656958539.6287155,
"presence_last_update_id": 1000,
}
/users/me/status:
post:
operationId: update-status
summary: Update your status
tags: ["users"]
description: |
Change your [status](/help/status-and-availability).
A request to this endpoint will only change the parameters passed.
For example, passing just `status_text` requests a change in the status
text, but will leave the status emoji unchanged.
Clients that wish to set the user's status to a specific value should
pass all supported parameters.
**Changes**: In Zulip 5.0 (feature level 86), added support for
`emoji_name`, `emoji_code`, and `reaction_type` parameters.
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
status_text:
type: string
description: |
The text content of the status message. Sending the empty string
will clear the user's status.
**Note**: The limit on the size of the message is 60 characters.
example: on vacation
away:
deprecated: true
type: boolean
description: |
Whether the user should be marked as "away".
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
starting with that feature level, `away` is a legacy way to
access the user's `presence_enabled` setting, with
`away = !presence_enabled`. To be removed in a future release.
example: true
emoji_name:
type: string
description: |
The name for the emoji to associate with this status.
**Changes**: New in Zulip 5.0 (feature level 86).
example: car
emoji_code:
type: string
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
**Changes**: New in Zulip 5.0 (feature level 86).
example: 1f697
reaction_type:
type: string
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86).
example: unicode_emoji
encoding:
away:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Client did not pass any new values.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when no changes were requested:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "status_text is too long (limit: 60 characters)",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the
`status_text` message exceeds the limit of
60 characters:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when `emoji_name` is not specified
but `emoji_code` or `reaction_type` is specified:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Emoji 'invalid' does not exist",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the emoji name does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid emoji name.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the emoji name is invalid:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid custom emoji.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the custom emoji is invalid:
/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), 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.
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
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.
# operationId can be used to record which view function
# corresponds to an endpoint. TODO: Add these for more
# endpoints, and perhaps use this to provide links to implementations.
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"
# TODO: Is this the best way to declare required elements in 200 responses?
- 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/Subscriptions"
example:
{
"msg": "",
"result": "success",
"subscriptions":
[
{
"audible_notifications": true,
"color": "#e79ab5",
"creator_id": null,
"description": "A Scandinavian country",
"desktop_notifications": true,
"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_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 privacy settings](/help/channel-permissions).
**Changes**: 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.
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"
stream_post_policy:
$ref: "#/components/schemas/ChannelPostPolicy"
message_retention_days:
$ref: "#/components/schemas/MessageRetentionDays"
can_remove_subscribers_group:
$ref: "#/components/schemas/CanRemoveSubscribersGroupId"
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
stream_post_policy:
contentType: application/json
can_remove_subscribers_group:
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 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_address}`: 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 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_address}`: 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`.
example:
{
"already_subscribed":
{"iago@zulip.com": ["testing-help"]},
"msg": "",
"result": "success",
"subscribed": {"newbie@zulip.com": ["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.
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.
example:
{
"msg": "",
"subscribed": {},
"already_subscribed": {"iago@zulip.com": ["Verona"]},
"not_removed": [],
"removed": ["testing-help"],
"result": "success",
}
delete:
operationId: unsubscribe
summary: Unsubscribe from a channel
tags: ["channels"]
description: |
Unsubscribe yourself or other users from one or more channels.
In addition to managing the current user's subscriptions, this
endpoint can be used to remove other users from channels. This
is possible in 3 situations:
- Organization administrators can remove any user from any
channel.
- Users can remove a bot that they own from any channel that
the user [can access](/help/channel-permissions).
- Users can unsubscribe any user from a channel if they [have
access](/help/channel-permissions) to the channel and are a
member of the [user group](/api/get-user-groups) specified
by the [`can_remove_subscribers_group`][can-remove-parameter]
for the channel.
**Changes**: 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.
Before Zulip 8.0 (feature level 197),
the `can_remove_subscribers_group` setting
was named `can_remove_subscribers_group_id`.
Before Zulip 7.0 (feature level 161), the
`can_remove_subscribers_group_id` for all channels was always
the system group for organization administrators.
Before Zulip 6.0 (feature level 145), users had no special
privileges for managing bots that they own.
[principals-param]: /api/unsubscribe#parameter-principals
[can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group
x-curl-examples-parameters:
oneOf:
- type: include
description: |
**Note**: Unsubscribing another user from a channel requires
administrative privileges.
parameters:
enum:
- subscriptions
- type: exclude
parameters:
enum:
- ""
description: |
You may specify the `principals` parameter like so:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subscriptions:
description: |
A list of channel names to unsubscribe from. This parameter is called
`streams` in our Python API.
type: array
items:
type: string
example: ["Verona", "Denmark"]
principals:
$ref: "#/components/schemas/Principals"
required:
- subscriptions
encoding:
subscriptions:
contentType: application/json
principals:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
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.
example:
{
"msg": "",
"not_removed": [],
"removed": ["testing-help"],
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/NonExistingChannelNameError"
- description: |
A typical failed JSON response for when the target channel does not exist:
/users/me/subscriptions/muted_topics:
patch:
deprecated: true
operationId: mute-topic
summary: Topic muting
tags: ["channels"]
description: |
[Mute or unmute a topic](/help/mute-a-topic) within a channel that
the current user is subscribed to.
**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting
to newer servers should use the [POST /user_topics](/api/update-user-topic)
endpoint, as this endpoint may be removed in a future release.
Before Zulip 7.0 (feature level 169), this endpoint
returned an error if asked to mute a topic that was already muted
or asked to unmute a topic that had not previously been muted.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- stream_id
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: |
The ID of the channel to access.
Clients must provide either `stream` or `stream_id` as a parameter
to this endpoint, but not both.
**Changes**: New in Zulip 2.0.0.
type: integer
example: 43
stream:
description: |
The name of the channel to access.
Clients must provide either `stream` or `stream_id` as a parameter
to this endpoint, but not both. Clients should use `stream_id`
instead of the `stream` parameter when possible.
type: string
example: Denmark
topic:
description: |
The topic to (un)mute. Note that the request will succeed regardless of
whether any messages have been sent to the specified topic.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
type: string
example: dinner
op:
description: |
Whether to mute (`add`) or unmute (`remove`) the provided topic.
type: string
enum:
- add
- remove
example: add
required:
- topic
- op
encoding:
stream_id:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/mobile_push/test_notification:
post:
operationId: test-notify
summary: Send a test notification to mobile device(s)
tags: ["mobile"]
description: |
Trigger sending a test push notification to the user's
selected mobile device or all of their mobile devices.
**Changes**: Starting with Zulip 8.0 (feature level 234), test
notifications sent via this endpoint use `test` rather than
`test-by-device-token` in the `event` field. Also, as of this
feature level, all mobile push notifications now include a
`realm_name` field.
New in Zulip 8.0 (feature level 217).
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: |
The push token for the device to which to send the test notification.
If this parameter is not submitted, the test notification will be sent
to all of the user's devices registered on the server.
A mobile client should pass this parameter, to avoid triggering a test
notification for other clients.
type: string
example: "111222"
responses:
"200":
description: Success.
content:
application/json:
schema:
$ref: "#/components/schemas/JsonSuccess"
"400":
description: |
Bad request.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/InvalidPushDeviceTokenError"
- $ref: "#/components/schemas/InvalidRemotePushDeviceTokenError"
/user_topics:
post:
operationId: update-user-topic
summary: Update personal preferences for a topic
tags: ["channels"]
description: |
This endpoint is used to update the personal preferences for a topic,
such as the topic's visibility policy, which is used to implement
[mute a topic](/help/mute-a-topic) and related features.
This endpoint can be used to update the visibility policy for the single
channel and topic pair indicated by the parameters for a user.
**Changes**: New in Zulip 7.0 (feature level 170). Previously,
toggling whether a topic was muted or unmuted was managed by the
[PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
stream_id:
description: |
The ID of the channel to access.
type: integer
example: 1
topic:
description: |
The topic for which the personal preferences needs to be updated.
Note that the request will succeed regardless of whether
any messages have been sent to the specified topic.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
type: string
example: dinner
visibility_policy:
description: |
Controls which visibility policy to set.
- 0 = None. Removes the visibility policy previously set for the topic.
- 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a channel.
- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted channel.
- 3 = Followed. [Follows the topic](/help/follow-a-topic).
In an unmuted channel, a topic visibility policy of unmuted will have the
same effect as the "None" visibility policy.
**Changes**: In Zulip 7.0 (feature level 219), added followed as
a visibility policy option.
type: integer
enum:
- 0
- 1
- 2
- 3
example: 1
required:
- stream_id
- topic
- visibility_policy
encoding:
stream_id:
contentType: application/json
visibility_policy:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/users/me/muted_users/{muted_user_id}:
post:
operationId: mute-user
summary: Mute a user
tags: ["users"]
description: |
[Mute a user](/help/mute-a-user) from the perspective of the requesting
user. Messages sent by muted users will be automatically marked as read
and hidden for the user who muted them.
Muted users should be implemented by clients as follows:
- The server will immediately mark all messages sent by the muted
user as read. This will automatically clear any existing mobile
push notifications related to the muted user.
- The server will mark any new messages sent by the muted user as read
for the requesting user's account, which prevents all email and mobile
push notifications.
- Clients should exclude muted users from presence lists or other UI
for viewing or composing one-on-one direct messages. One-on-one direct
messages sent by muted users should be hidden everywhere in the Zulip UI.
- Channel messages and group direct messages sent by the muted
user should avoid displaying the content and name/avatar,
but should display that N messages by a muted user were
hidden (so that it is possible to interpret the messages by
other users who are talking with the muted user).
- Group direct message conversations including the muted user
should display muted users as "Muted user", rather than
showing their name, in lists of such conversations, along with using
a blank grey avatar where avatars are displayed.
- Administrative/settings UI elements for showing "All users that exist
on this channel or realm", e.g. for organization
administration or showing channel subscribers, should display
the user's name as normal.
**Changes**: New in Zulip 4.0 (feature level 48).
parameters:
- $ref: "#/components/parameters/MutedUserId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Cannot mute self",
"result": "error",
}
description: |
An example JSON response for when the user ID is the current
user's ID:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "No such user",
"result": "error",
}
description: |
An example JSON response for when the user is nonexistent or inaccessible:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User already muted",
"result": "error",
}
description: |
An example JSON response for when the user is already muted:
delete:
operationId: unmute-user
summary: Unmute a user
tags: ["users"]
description: |
[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users)
from the perspective of the requesting user.
**Changes**: New in Zulip 4.0 (feature level 48).
parameters:
- $ref: "#/components/parameters/MutedUserId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "No such user",
"result": "error",
}
description: |
An example JSON response for when the user is nonexistent or inaccessible:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User is not muted",
"result": "error",
}
description: |
An example JSON response for when the user is not previously muted:
/users/me/apns_device_token:
post:
operationId: add-apns-token
summary: Add an APNs device token
tags: ["users"]
description: |
This endpoint adds an APNs device token to register for iOS push notifications.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: |
The token provided by the device.
type: string
example: apple-tokenbb
appid:
description: |
The ID of the Zulip app that is making the request.
**Changes**: In Zulip 8.0 (feature level 223), this parameter was made
required. Previously, if it was unspecified, the server would use a default
value (based on the `ZULIP_IOS_APP_ID` server setting, which
defaulted to `"org.zulip.Zulip"`).
type: string
example: org.zulip.Zulip
required:
- token
- appid
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when the token's length is invalid
or it is empty:
example:
{
"result": "error",
"msg": "Empty or invalid length token",
"code": "BAD_REQUEST",
}
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid APNS token",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the APNs token is invalid:
delete:
operationId: remove-apns-token
summary: Remove an APNs device token
tags: ["users"]
description: |
This endpoint removes an APNs device token for iOS push notifications.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: |
The token provided by the device.
type: string
example: apple-tokenbb
required:
- token
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when the token's length is invalid
or it is empty:
example:
{
"result": "error",
"msg": "Empty or invalid length token",
"code": "BAD_REQUEST",
}
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Token does not exist",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the token does not exist:
/users/me/android_gcm_reg_id:
post:
operationId: add-fcm-token
summary: Add an FCM registration token
tags: ["users"]
description: |
This endpoint adds an FCM registration token for push notifications.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: |
The token provided by the device.
type: string
example: android-token
required:
- token
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when the token's length is invalid
or is empty:
example:
{
"result": "error",
"msg": "Empty or invalid length token",
"code": "BAD_REQUEST",
}
delete:
operationId: remove-fcm-token
summary: Remove an FCM registration token
tags: ["users"]
description: |
This endpoint removes an FCM registration token for push notifications.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
description: |
The token provided by the device.
type: string
example: android-token
required:
- token
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
A typical failed JSON response for when the token's length is invalid
or is empty:
example:
{
"result": "error",
"msg": "Empty or invalid length token",
"code": "BAD_REQUEST",
}
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Token does not exist",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the token does not exist:
/users/{user_id}/subscriptions/{stream_id}:
get:
operationId: get-subscription-status
summary: Get subscription status
tags: ["channels"]
description: |
Check whether a user is subscribed to a channel.
**Changes**: New in Zulip 3.0 (feature level 12).
parameters:
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/ChannelIdInPath"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
is_subscribed:
type: boolean
description: |
Whether the user is subscribed to the channel.
example:
{"msg": "", "result": "success", "is_subscribed": false}
/realm/emoji/{emoji_name}:
post:
operationId: upload-custom-emoji
summary: Upload custom emoji
tags: ["server_and_organizations"]
description: |
This endpoint is used to upload a custom emoji for use in the user's
organization. Access to this endpoint depends on the
[organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji).
x-parameter-description: |
As described above, the image file to upload must be provided in the
request's body.
## Maximum file size
The maximum file size for uploads can be configured by the
administrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB`
in the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults
to 5MB.
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
parameters:
- name: emoji_name
required: true
in: path
description: |
The name that should be associated with the uploaded emoji image/gif.
The emoji name can only contain letters, numbers, dashes, and spaces.
Upper and lower case letters are treated the same, and underscores (\_)
are treated the same as spaces (consistent with how the Zulip UI
handles emoji).
schema:
type: string
example: smile
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filename:
type: string
format: binary
example: /path/to/img.png
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
delete:
operationId: deactivate-custom-emoji
summary: Deactivate custom emoji
tags: ["server_and_organizations"]
description: |
[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from
the user's organization.
Users can only deactivate custom emoji that they added themselves except for
organization administrators, who can deactivate any custom emoji.
Note that deactivated emoji will still be visible in old messages, reactions,
user statuses and channel descriptions.
**Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an
HTTP status code of 400 when the emoji did not exist, instead of 404.
parameters:
- name: emoji_name
required: true
in: path
description: |
The name of the custom emoji to deactivate.
schema:
type: string
example: green_tick
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
An example JSON response for when no emoji exists with the provided name:
example:
{
"code": "BAD_REQUEST",
"result": "error",
"msg": "Emoji 'green_tick' does not exist",
}
/realm/emoji:
get:
operationId: get-custom-emoji
summary: Get all custom emoji
tags: ["server_and_organizations"]
description: |
Get all the custom emoji in the user's organization.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
emoji:
type: object
description: |
An object that contains `emoji` objects, each identified with their
emoji ID as the key.
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
example:
{
"result": "success",
"msg": "",
"emoji":
{
"1":
{
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
"deactivated": false,
"author_id": 5,
},
},
}
/realm/presence:
get:
operationId: get-presence
summary: Get presence of all users
tags: ["server_and_organizations"]
description: |
Get the presence information of all the users in an organization.
If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level
setting is set to `true`, presence information of only accessible
users are returned.
See [Zulip's developer documentation][subsystems-presence]
for details on the data model for presence in Zulip.
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
server_timestamp:
type: number
description: |
The time when the server fetched the `presences` data included
in the response.
presences:
type: object
description: |
A dictionary where each entry describes the presence details
of a user in the Zulip organization.
additionalProperties:
type: object
description: |
`{user_email}`: Object containing the details of a user's presence.
The object's key is the user's Zulip API email.
additionalProperties:
$ref: "#/components/schemas/LegacyPresenceFormat"
example:
{
"msg": "",
"presences":
{
"iago@zulip.com":
{
"website":
{
"client": "website",
"pushable": false,
"status": "active",
"timestamp": 1656958485,
},
"aggregated":
{
"client": "website",
"status": "active",
"timestamp": 1656958485,
},
},
},
"result": "success",
"server_timestamp": 1656958539.6287155,
}
/realm/profile_fields:
get:
operationId: get-custom-profile-fields
summary: Get all custom profile fields
tags: ["server_and_organizations"]
description: |
Get all the [custom profile fields](/help/custom-profile-fields)
configured for the user's organization.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
custom_fields:
type: array
description: |
An array containing all the custom profile fields defined in this
Zulip organization.
items:
$ref: "#/components/schemas/CustomProfileField"
example:
{
"result": "success",
"msg": "",
"custom_fields":
[
{
"id": 1,
"name": "Phone number",
"type": 1,
"hint": "",
"field_data": "",
"order": 1,
"required": true,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
"required": true,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
"required": false,
},
{
"id": 4,
"name": "Favorite editor",
"type": 3,
"hint": "",
"field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}',
"order": 4,
"display_in_profile_summary": true,
"required": true,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
"required": false,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
"display_in_profile_summary": true,
"required": false,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
"required": true,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
"required": true,
},
{
"id": 9,
"name": "Pronouns",
"type": 8,
"hint": "What pronouns should people use to refer to you?",
"order": 9,
"required": false,
},
],
}
patch:
operationId: reorder-custom-profile-fields
summary: Reorder custom profile fields
tags: ["server_and_organizations"]
description: |
Reorder the custom profile fields in the user's organization.
Custom profile fields are displayed in Zulip UI widgets in order; this
endpoint allows administrative settings UI to change the field ordering.
This endpoint is used to implement the dragging feature described in the
[custom profile fields documentation](/help/custom-profile-fields).
x-requires-administrator: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
order:
description: |
A list of the IDs of all the custom profile fields defined in this
organization, in the desired new order.
type: array
items:
type: integer
example: [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
required:
- order
encoding:
order:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
post:
operationId: create-custom-profile-field
summary: Create a custom profile field
tags: ["server_and_organizations"]
description: |
[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.
x-requires-administrator: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
description: |
The name of the custom profile field, which will appear both in
user-facing settings UI for configuring custom profile fields and
in UI displaying a user's profile.
type: string
example: "Favorite programming language"
hint:
description: |
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
type: string
example: "Your favorite programming language."
field_type:
description: |
The field type can be any of the supported custom profile field types. See the
[custom profile fields documentation](/help/custom-profile-fields)
for more details on what each type means.
- **1**: Short text
- **2**: Long text
- **3**: List of options
- **4**: Date picker
- **5**: Link
- **6**: Person picker
- **7**: External account
- **8**: Pronouns
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
type: integer
example: 3
field_data:
description: |
Field types 3 (List of options) and 7 (External account) support storing
additional configuration for the field type in the `field_data` attribute.
For field type 3 (List of options), this attribute is a JSON dictionary
defining the choices and the order they will be displayed in the
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
type: object
example:
{
"python": {"text": "Python", "order": "1"},
"java": {"text": "Java", "order": "2"},
}
display_in_profile_summary:
description: |
Whether clients should display this profile field in a summary section of a
user's profile (or in a more easily accessible "small profile").
At most 2 profile fields may have this property be true in a given
organization. The "Long text" [profile field types][profile-field-types]
profile field types cannot be selected to be displayed in profile summaries.
The "Person picker" profile field is also not supported, but that is likely to
be temporary.
[profile-field-types]: /help/custom-profile-fields#profile-field-types
**Changes**: New in Zulip 6.0 (feature level 146).
type: boolean
example: true
required:
description: |
Whether an organization administrator has configured this profile field as
required.
Because the required property is mutable, clients cannot assume that a required
custom profile field has a value. The Zulip web application displays a prominent
banner to any user who has not set a value for a required field.
**Changes**: New in Zulip 9.0 (feature level 244).
type: boolean
example: true
required:
- field_type
encoding:
field_type:
contentType: application/json
field_data:
contentType: application/json
display_in_profile_summary:
contentType: application/json
required:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
id:
type: integer
description: |
The ID for the custom profile field.
example: {"result": "success", "msg": "", "id": 9}
/realm/user_settings_defaults:
patch:
operationId: update-realm-user-settings-defaults
summary: Update realm-level defaults of user settings
tags: ["server_and_organizations"]
x-requires-administrator: true
description: |
Change the [default values of settings][new-user-defaults] for new users
joining the organization. Essentially all
[personal preference settings](/api/update-settings) are supported.
This feature can be invaluable for customizing Zulip's default
settings for notifications or UI to be appropriate for how the
organization is using Zulip. (Note that this only supports
personal preference settings, like when to send push
notifications or what emoji set to use, not profile or
identity settings that naturally should be different for each user).
Note that this endpoint cannot, at present, be used to modify
settings for existing users in any way.
**Changes**: New in Zulip 5.0 (feature level 96). If any parameters
sent in the request are not supported by this endpoint, an
[`ignored_parameters_unsupported`][ignored-parameters] array will
be returned in the JSON success response.
[new-user-defaults]: /help/configure-default-new-user-settings
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- left_side_userlist
- emojiset
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
dense_mode:
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
type: boolean
example: true
starred_message_counts:
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
type: boolean
example: true
receives_typing_notifications:
description: |
Whether the user is configured to receive typing notifications from other users.
The server will only deliver typing notifications events to users who for whom this
is enabled.
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
only options to disable sending typing notifications.
type: boolean
example: true
fluid_layout_width:
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent conversations) on wide screens.
type: boolean
example: true
high_contrast_mode:
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
type: boolean
example: true
web_mark_read_on_scroll_policy:
description: |
Whether or not to mark messages as read when the user scrolls through their
feed.
- 1 - Always
- 2 - Only in conversation views
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
way for the user to configure this behavior on the web, and the Zulip web and
desktop apps behaved like the "Always" setting when marking messages as read.
type: integer
enum:
- 1
- 2
- 3
example: 1
web_channel_default_view:
description: |
Web/desktop app setting controlling the default navigation
behavior when clicking on a channel link.
- 1 - Top topic in the channel
- 2 - Channel feed
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
was not configurable, and every user had the "Channel feed" behavior.
type: integer
enum:
- 1
- 2
example: 1
web_font_size_px:
description: |
User-configured primary `font-size` for the web application, in pixels.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
only adjustable via browser zoom. Note that this setting was not fully
implemented at this feature level.
type: integer
example: 14
web_line_height_percent:
description: |
User-configured primary `line-height` for the web application, in percent, so a
value of 120 represents a `line-height` of 1.2.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
not user-configurable. Note that this setting was not fully implemented at this
feature level.
type: integer
example: 122
color_scheme:
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
type: integer
enum:
- 1
- 2
- 3
example: 1
enable_drafts_synchronization:
description: |
A boolean parameter to control whether synchronizing drafts is enabled for
the user. When synchronization is disabled, all drafts stored in the server
will be automatically deleted from the server.
This does not do anything (like sending events) to delete local copies of
drafts stored in clients.
type: boolean
example: true
translate_emoticons:
description: |
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
in messages the user sends.
type: boolean
example: true
display_emoji_reaction_users:
description: |
Whether to display the names of reacting users on a message.
When enabled, clients should display the names of reacting users, rather than
a count, for messages with few total reactions. The ideal cutoff may depend on
the space available for displaying reactions; the official web application
displays names when 3 or fewer total reactions are present with this setting
enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
type: boolean
example: false
web_home_view:
description: |
The [home view](/help/configure-home-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent conversations view
- "inbox" - Inbox view
- "all_messages" - Combined feed view
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
called `default_view`, which was new in Zulip 4.0 (feature level 42).
type: string
example: all_messages
web_escape_navigates_to_home_view:
description: |
Whether the escape key navigates to the
[configured home view](/help/configure-home-view).
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called
`escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107).
type: boolean
example: true
left_side_userlist:
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
type: boolean
example: true
emojiset:
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google
- "twitter" - Twitter
- "text" - Plain text
- "google-blob" - Google blobs
type: string
example: "google"
demote_inactive_streams:
description: |
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
type: integer
enum:
- 1
- 2
- 3
example: 1
user_list_style:
description: |
The style selected by the user for the right sidebar user list.
- 1 - Compact
- 2 - With status
- 3 - With avatar and status
**Changes**: New in Zulip 6.0 (feature level 141).
type: integer
enum:
- 1
- 2
- 3
example: 1
web_animate_image_previews:
description: |
Controls how animated images should be played in the message feed in the web/desktop application.
- "always" - Always play the animated images in the message feed.
- "on_hover" - Play the animated images on hover over them in the message feed.
- "never" - Never play animated images in the message feed.
**Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images
always used to play in the message feed by default. This setting controls this
behaviour.
type: string
enum:
- always
- on_hover
- never
example: on_hover
web_stream_unreads_count_display_policy:
description: |
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
Channels that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All channels
- 2 - Unmuted channels and topics
- 3 - No channels
**Changes**: New in Zulip 8.0 (feature level 210).
type: integer
enum:
- 1
- 2
- 3
example: 2
enable_stream_desktop_notifications:
description: |
Enable visual desktop notifications for channel messages.
type: boolean
example: true
enable_stream_email_notifications:
description: |
Enable email notifications for channel messages.
type: boolean
example: true
enable_stream_push_notifications:
description: |
Enable mobile notifications for channel messages.
type: boolean
example: true
enable_stream_audible_notifications:
description: |
Enable audible desktop notifications for channel messages.
type: boolean
example: true
notification_sound:
description: |
Notification sound name.
type: string
example: ding
enable_desktop_notifications:
description: |
Enable visual desktop notifications for direct messages and @-mentions.
type: boolean
example: true
enable_sounds:
description: |
Enable audible desktop notifications for direct messages and
@-mentions.
type: boolean
example: true
enable_followed_topic_desktop_notifications:
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
enable_followed_topic_email_notifications:
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
enable_followed_topic_push_notifications:
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: false
enable_followed_topic_audible_notifications:
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: false
email_notifications_batching_period_seconds:
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
type: integer
example: 120
enable_offline_email_notifications:
description: |
Enable email notifications for direct messages and @-mentions received
when the user is offline.
type: boolean
example: true
enable_offline_push_notifications:
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is offline.
type: boolean
example: true
enable_online_push_notifications:
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is online.
type: boolean
example: true
enable_digest_emails:
description: |
Enable digest emails when the user is away.
type: boolean
example: true
message_content_in_email_notifications:
description: |
Include the message's content in email notifications for new messages.
type: boolean
example: true
pm_content_in_desktop_notifications:
description: |
Include content of direct messages in desktop notifications.
type: boolean
example: true
wildcard_mentions_notify:
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
type: boolean
example: true
enable_followed_topic_wildcard_mentions_notify:
description: |
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
should send notifications like a personal mention.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
desktop_icon_count_display:
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unread messages
- 2 - DMs, mentions, and followed topics
- 3 - DMs and mentions
- 4 - None
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed
topics` option, renumbering the options to insert it in order.
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
realm_name_in_email_notifications_policy:
description: |
Whether to [include organization name in subject of message notification
emails](/help/email-notifications#include-organization-name-in-subject-line).
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
previous `realm_name_in_notifications` boolean;
`true` corresponded to `Always`, and `false` to `Never`.
type: integer
enum:
- 1
- 2
- 3
example: 1
automatically_follow_topics_policy:
description: |
Which [topics to follow automatically](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
automatically_unmute_topics_in_muted_streams_policy:
description: |
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
automatically_follow_topics_where_mentioned:
description: |
Whether the server will automatically mark the user as following
topics where the user is mentioned.
**Changes**: New in Zulip 8.0 (feature level 235).
type: boolean
example: true
presence_enabled:
description: |
Display the presence status to other users when online.
type: boolean
example: true
enter_sends:
description: |
Whether pressing Enter in the compose box sends a message
(or saves a message edit).
type: boolean
example: true
twenty_four_hour_time:
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
**Changes**: New in Zulip 5.0 (feature level 99).
Previously, this default was edited using the
`default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint.
type: boolean
example: true
send_private_typing_notifications:
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
direct messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
send_stream_typing_notifications:
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
channel messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
send_read_receipts:
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
email_address_visibility:
description: |
The [policy][permission-level] for [which other users][help-email-visibility]
in this organization can see the user's real email address.
- 1 = Everyone
- 2 = Members only
- 3 = Administrators only
- 4 = Nobody
- 5 = Moderators only
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
realm-level setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[help-email-visibility]: /help/configure-email-visibility
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
example: 1
web_navigate_to_sent_message:
description: |
Web/desktop app setting for whether the user's view should
automatically go to the conversation where they sent a message.
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
this behavior was not configurable.
type: boolean
example: true
encoding:
dense_mode:
contentType: application/json
starred_message_counts:
contentType: application/json
receives_typing_notifications:
contentType: application/json
fluid_layout_width:
contentType: application/json
high_contrast_mode:
contentType: application/json
web_mark_read_on_scroll_policy:
contentType: application/json
web_channel_default_view:
contentType: application/json
web_font_size_px:
contentType: application/json
web_line_height_percent:
contentType: application/json
color_scheme:
contentType: application/json
enable_drafts_synchronization:
contentType: application/json
translate_emoticons:
contentType: application/json
display_emoji_reaction_users:
contentType: application/json
web_escape_navigates_to_home_view:
contentType: application/json
left_side_userlist:
contentType: application/json
demote_inactive_streams:
contentType: application/json
user_list_style:
contentType: application/json
web_stream_unreads_count_display_policy:
contentType: application/json
enable_stream_desktop_notifications:
contentType: application/json
enable_stream_email_notifications:
contentType: application/json
enable_stream_push_notifications:
contentType: application/json
enable_stream_audible_notifications:
contentType: application/json
enable_desktop_notifications:
contentType: application/json
enable_sounds:
contentType: application/json
enable_followed_topic_desktop_notifications:
contentType: application/json
enable_followed_topic_email_notifications:
contentType: application/json
enable_followed_topic_push_notifications:
contentType: application/json
enable_followed_topic_audible_notifications:
contentType: application/json
email_notifications_batching_period_seconds:
contentType: application/json
enable_offline_email_notifications:
contentType: application/json
enable_offline_push_notifications:
contentType: application/json
enable_online_push_notifications:
contentType: application/json
enable_digest_emails:
contentType: application/json
message_content_in_email_notifications:
contentType: application/json
pm_content_in_desktop_notifications:
contentType: application/json
wildcard_mentions_notify:
contentType: application/json
enable_followed_topic_wildcard_mentions_notify:
contentType: application/json
desktop_icon_count_display:
contentType: application/json
realm_name_in_email_notifications_policy:
contentType: application/json
automatically_follow_topics_policy:
contentType: application/json
automatically_unmute_topics_in_muted_streams_policy:
contentType: application/json
automatically_follow_topics_where_mentioned:
contentType: application/json
presence_enabled:
contentType: application/json
enter_sends:
contentType: application/json
twenty_four_hour_time:
contentType: application/json
send_private_typing_notifications:
contentType: application/json
send_stream_typing_notifications:
contentType: application/json
send_read_receipts:
contentType: application/json
email_address_visibility:
contentType: application/json
web_navigate_to_sent_message:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SuccessIgnoredParameters"
/users/me/subscriptions/properties:
post:
operationId: update-subscription-settings
summary: Update subscription settings
tags: ["channels"]
description: |
This endpoint is used to update the user's personal settings for the
channels they are subscribed to, including muting, color, pinning, and
per-channel notification settings.
**Changes**: Prior to Zulip 5.0 (feature level 111), response
object included the `subscription_data` in the
request. The endpoint now returns the more ergonomic
[`ignored_parameters_unsupported`][ignored-parameters] array instead.
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subscription_data:
description: |
A list of objects that describe the changes that should be applied in
each subscription. Each object represents a subscription, and must have
a `stream_id` key that identifies the channel, as well as the `property`
being modified and its new `value`.
type: array
items:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a channel.
property:
type: string
enum:
- color
- is_muted
- in_home_view
- pin_to_top
- desktop_notifications
- audible_notifications
- push_notifications
- email_notifications
- wildcard_mentions_notify
description: |
One of the channel properties described below:
- `"color"`: The hex value of the user's display color for the channel.
- `"is_muted"`: Whether the channel is [muted](/help/mute-a-channel).<br>
**Changes**: As of Zulip 6.0 (feature level 139), updating either
`"is_muted"` or `"in_home_view"` generates two [subscription update
events](/api/get-events#subscription-update), one for each property,
that are sent to clients. Prior to this feature level, updating either
property only generated a subscription update event for
`"in_home_view"`. <br>
Prior to Zulip 2.1.0, this feature was represented
by the more confusingly named `"in_home_view"` (with the
opposite value: `in_home_view=!is_muted`); for
backwards-compatibility, modern Zulip still accepts that property.
- `"pin_to_top"`: Whether to pin the channel at the top of the channel list.
- `"desktop_notifications"`: Whether to show desktop notifications
for all messages sent to the channel.
- `"audible_notifications"`: Whether to play a sound
notification for all messages sent to the channel.
- `"push_notifications"`: Whether to trigger a mobile push
notification for all messages sent to the channel.
- `"email_notifications"`: Whether to trigger an email
notification for all messages sent to the channel.
- `"wildcard_mentions_notify"`: Whether wildcard mentions trigger
notifications as though they were personal mentions in this channel.
value:
oneOf:
- type: boolean
- type: string
description: |
The new value of the property being modified.
If the property is `"color"`, then `value` is a string
representing the hex value of the user's display
color for the channel. For all other above properties,
`value` is a boolean.
required:
- stream_id
- property
- value
example:
{"stream_id": 2, "property": "is_muted", "value": true}
example:
[
{"stream_id": 1, "property": "pin_to_top", "value": true},
{"stream_id": 3, "property": "color", "value": "#f00f00"},
]
required:
- subscription_data
encoding:
subscription_data:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SuccessIgnoredParameters"
/users/{email}:
get:
operationId: get-user-by-email
summary: Get a user by email
tags: ["users"]
description: |
Fetch details for a single user in the organization given a Zulip
API email address.
You can also fetch details on [all users in the organization](/api/get-users)
or [by user ID](/api/get-user).
Fetching by user ID is generally recommended when possible,
as a user might [change their email address](/help/change-your-email-address)
or change their [email address visibility](/help/configure-email-visibility),
either of which could change the value of their Zulip API email address.
**Changes**: New in Zulip Server 4.0 (feature level 39).
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
parameters:
- name: email
in: path
description: |
The Zulip API email address of the user whose details you want to fetch.
schema:
type: string
example: iago@zulip.com
required: true
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"user":
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "0"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
"delivery_email": null,
},
}
/users/{user_id}:
get:
operationId: get-user
summary: Get a user
tags: ["users"]
description: |
Fetch details for a single user in the organization.
You can also fetch details on [all users in the organization](/api/get-users)
or [by a user's Zulip API email](/api/get-user-by-email).
**Changes**: New in Zulip 3.0 (feature level 1).
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
parameters:
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"user":
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "0"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
"delivery_email": null,
},
}
patch:
operationId: update-user
summary: Update a user
tags: ["users"]
x-requires-administrator: true
description: |
Administrative endpoint to update the details of another user in the organization.
Supports everything an administrator can do to edit details of another
user's account, including editing full name,
[role](/help/roles-and-permissions), and [custom profile
fields](/help/custom-profile-fields).
parameters:
- $ref: "#/components/parameters/UserId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
full_name:
description: |
The user's full name.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 5.0 (feature level 106).
type: string
example: NewName
role:
description: |
New [role](/api/roles-and-permissions) for the user. Roles are encoded as:
- Organization owner: 100
- Organization administrator: 200
- Organization moderator: 300
- Member: 400
- Guest: 600
Only organization owners can add or remove the owner role.
The owner role cannot be removed from the only organization owner.
**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous
pair of `is_admin` and `is_guest` boolean parameters. Organization moderator
role added in Zulip 4.0 (feature level 60).
type: integer
example: 400
profile_data:
description: |
A dictionary containing the to be updated custom profile field data for the user.
type: array
items:
type: object
example:
[{"id": 4, "value": "0"}, {"id": 5, "value": "1909-04-05"}]
encoding:
role:
contentType: application/json
profile_data:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Guests cannot be organization administrators",
"code": "BAD_REQUEST",
}
description: |
A typical unsuccessful JSON response:
delete:
operationId: deactivate-user
summary: Deactivate a user
tags: ["users"]
x-requires-administrator: true
description: |
[Deactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
parameters:
- $ref: "#/components/parameters/UserId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
deactivation_notification_comment:
description: |
If not `null`, requests that the deactivated user receive
a notification email about their account deactivation.
If not `""`, encodes custom text written by the administrator
to be included in the notification email.
**Changes**: New in Zulip 5.0 (feature level 135).
type: string
example: |
Farewell!
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Cannot deactivate the only organization owner",
"result": "error",
}
description: |
An example JSON error response when attempting to deactivate the only
organization owner in an organization:
/realm/linkifiers:
get:
operationId: get-linkifiers
summary: Get linkifiers
tags: ["server_and_organizations"]
description: |
List all of an organization's configured
[linkifiers](/help/add-a-custom-linkifier), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
**Changes**: New in Zulip 4.0 (feature level 54). On older versions,
a similar `GET /realm/filters` endpoint was available with each entry in
a `[pattern, url_format, id]` tuple format.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
linkifiers:
type: array
description: |
An ordered array of objects, where each object
describes a linkifier.
Clients should always process linkifiers in the order given;
this is important if the realm has linkifiers with overlapping
patterns. The order can be modified using [`PATCH
/realm/linkifiers`](/api/reorder-linkifiers).
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The string regex pattern which represents the pattern that
should be linkified by this linkifier.
url_template:
type: string
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant
URL template to be used for linkifying matches.
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
which contained a URL format string.
id:
type: integer
description: |
The ID of the linkifier.
example:
{
"msg": "",
"linkifiers":
[
{
"pattern": "#(?P<id>[0-9]+)",
"url_template": "https://github.com/zulip/zulip/issues/{id}",
"id": 1,
},
],
"result": "success",
}
patch:
operationId: reorder-linkifiers
summary: Reorder linkifiers
tags: ["server_and_organizations"]
description: |
Change the order that the regular expression patterns in the organization's
[linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics.
Useful when defining linkifiers with overlapping patterns.
**Changes**: New in Zulip 8.0 (feature level 202). Before this feature level,
linkifiers were always processed in order by ID, which meant users would
need to delete and recreate them to reorder the list of linkifiers.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
ordered_linkifier_ids:
description: |
A list of the IDs of all the linkifiers defined in this
organization, in the desired new order.
type: array
items:
type: integer
example: [3, 2, 1, 5]
required:
- ordered_linkifier_ids
encoding:
ordered_linkifier_ids:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/realm/filters:
post:
operationId: add-linkifier
summary: Add a linkifier
tags: ["server_and_organizations"]
description: |
Configure [linkifiers](/help/add-a-custom-linkifier),
regular expression patterns that are automatically linkified when they
appear in messages and topics.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
pattern:
$ref: "#/components/schemas/LinkifierPattern"
url_template:
$ref: "#/components/schemas/LinkifierURLTemplate"
required:
- pattern
- url_template
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
id:
type: integer
description: |
The numeric ID assigned to this filter.
example: {"id": 42, "result": "success", "msg": ""}
/realm/filters/{filter_id}:
delete:
operationId: remove-linkifier
summary: Remove a linkifier
tags: ["server_and_organizations"]
description: |
Remove [linkifiers](/help/add-a-custom-linkifier), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
parameters:
- name: filter_id
in: path
description: |
The ID of the linkifier that you want to remove.
schema:
type: integer
example: 43
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
patch:
operationId: update-linkifier
summary: Update a linkifier
tags: ["server_and_organizations"]
description: |
Update a [linkifier](/help/add-a-custom-linkifier), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
**Changes**: New in Zulip 4.0 (feature level 57).
parameters:
- name: filter_id
in: path
description: |
The ID of the linkifier that you want to update.
schema:
type: integer
example: 5
required: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
pattern:
$ref: "#/components/schemas/LinkifierPattern"
url_template:
$ref: "#/components/schemas/LinkifierURLTemplate"
required:
- pattern
- url_template
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/realm/playgrounds:
post:
operationId: add-code-playground
summary: Add a code playground
tags: ["server_and_organizations"]
description: |
Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.
**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was
fixed in Zulip 4.0 (feature level 57).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
description: |
The user-visible display name of the playground which can be
used to pick the target playground, especially when multiple
playground options exist for that programming language.
type: string
example: Python playground
pygments_language:
description: |
The name of the Pygments language lexer for that
programming language.
type: string
example: Python
url_template:
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
compliant URL template for the playground. The template should
contain exactly one variable named `code`, which determines how the
extracted code should be substituted in the playground URL.
**Changes**: New in Zulip 8.0 (feature level 196). This replaced the
`url_prefix` parameter, which was used to construct URLs by just
concatenating `url_prefix` and `code`.
type: string
example: https://python.example.com?code={code}
required:
- name
- pygments_language
- url_template
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
id:
type: integer
description: |
The numeric ID assigned to this playground.
example: {"id": 1, "result": "success", "msg": ""}
/realm/playgrounds/{playground_id}:
delete:
operationId: remove-code-playground
summary: Remove a code playground
tags: ["server_and_organizations"]
description: |
Remove a [code playground](/help/code-blocks#code-playgrounds) previously
configured for an organization.
**Changes**: New in Zulip 4.0 (feature level 49).
parameters:
- name: playground_id
in: path
description: |
The ID of the playground that you want to remove.
schema:
type: integer
example: 1
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
/export/realm:
get:
operationId: get-realm-exports
summary: Get all public data exports
tags: ["server_and_organizations"]
x-requires-administrator: true
description: |
Fetch all public [data exports](/help/export-your-organization)
of the organization.
**Changes**: New in Zulip 2.1.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
exports:
type: array
description: |
An array of dictionaries where each dictionary contains
details about a public data export of the organization.
items:
$ref: "#/components/schemas/RealmExport"
example:
{
"exports":
[
{
"acting_user_id": 11,
"deleted_timestamp": null,
"export_time": 1722243168.134179,
"export_url": "http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz",
"id": 323,
"failed_timestamp": null,
"pending": false,
},
],
"msg": "",
"result": "success",
}
post:
operationId: export-realm
summary: Create a public data export
tags: ["server_and_organizations"]
x-requires-administrator: true
description: |
Create a public [data export](/help/export-your-organization)
of the organization.
!!! warn ""
**Note**: If you're the administrator of a self-hosted installation,
you may be looking for the documentation on [server data export and
import][data-export] or [server backups][backups].
**Changes**: New in Zulip 2.1.
[data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export
[backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
id:
type: integer
description: |
The ID of the public data export created.
**Changes**: New in Zulip 7.0 (feature level 182).
example: {"id": 1, "result": "success", "msg": ""}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Please request a manual export from zulip-admin@example.com.",
"result": "error",
}
description: |
An example JSON error response for when the public data export
exceeds the maximum allowed data export size.
/invites:
get:
operationId: get-invites
summary: Get all invitations
tags: ["invites"]
description: |
Fetch all unexpired [invitations](/help/invite-new-users) (i.e. email
invitations and reusable invitation links) that can be managed by the user.
Note that administrators can manage invitations that were created by other users.
**Changes**: Prior to Zulip 8.0 (feature level 209), non-admin users could
only create email invitations, and therefore the response would never include
reusable invitation links for these users.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
invites:
type: array
description: |
An array of objects, each representing a single unexpired
[invitation](/help/invite-new-users).
items:
$ref: "#/components/schemas/Invite"
example:
{
"result": "success",
"msg": "",
"invites":
[
{
email: "example@zulip.com",
expiry_date: null,
id: 1,
invited: 1710606654,
invited_as: 200,
invited_by_user_id: 9,
notify_referrer_on_join: true,
is_multiuse: false,
},
{
expiry_date: 1711463862,
id: 1,
invited: 1710599862,
invited_as: 400,
invited_by_user_id: 9,
is_multiuse: true,
notify_referrer_on_join: true,
link_url: "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/",
},
],
}
post:
operationId: send-invites
summary: Send invitations
tags: ["invites"]
description: |
Send [invitations](/help/invite-new-users) to specified email addresses.
**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
parameter was removed and replaced by `invite_expires_in_minutes`.
In Zulip 5.0 (feature level 117), added support for passing `null` as
the `invite_expires_in_days` parameter to request an invitation that never
expires.
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
added which specified the number of days before the invitation would expire.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
invitee_emails:
description: |
The string containing the email addresses, separated by commas or
newlines, that will be sent an invitation.
type: string
example: example@zulip.com, logan@zulip.com
invite_expires_in_minutes:
$ref: "#/components/schemas/InviteExpirationParameter"
invite_as:
$ref: "#/components/schemas/InviteRoleParameter"
stream_ids:
description: |
A list containing the [IDs of the channels](/api/get-stream-id) that the
newly created user will be automatically subscribed to if the invitation
is accepted, in addition to any default channels that the new user may
be subscribed to based on the `include_realm_default_subscriptions`
parameter.
This list must be empty if the current user has the unlikely
configuration of being able to send invitations while lacking
permission to [subscribe other users to channels][can-subscribe-others].
**Changes**: Before Zulip 7.0 (feature level 180), specifying `stream_ids`
as an empty list resulted in an error.
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
type: array
items:
type: integer
example: [1, 10]
include_realm_default_subscriptions:
description: |
Boolean indicating whether the newly created user should be subscribed
to the [default channels][default-channels] for the organization.
Note that this parameter can be `true` even if the user creating the
invitation does not generally have permission to [subscribe other
users to channels][can-subscribe-others].
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
of Zulip behaved as though this parameter was always `false`; clients
needed to include the organization's default channels in the
`stream_ids` parameter for a newly created user to be automatically
subscribed to them.
[default-channels]: /help/set-default-channels-for-new-users
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
type: boolean
default: false
example: false
notify_referrer_on_join:
description: |
A boolean indicating whether the referrer would like to receive a
direct message from [notification
bot](/help/configure-automated-notices) when a user account is created
using this invitation.
**Changes**: New in Zulip 9.0 (feature level 267). Previously,
referrers always received such direct messages.
type: boolean
example: false
default: true
required:
- invitee_emails
- stream_ids
encoding:
invite_expires_in_minutes:
contentType: application/json
stream_ids:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvitationFailedError"
- example:
{
"result": "error",
"msg": "Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!",
"errors":
[
[
"hamlet@zulip.com",
"Already has an account.",
false,
],
],
"sent_invitations": true,
"license_limit_reached": false,
"daily_limit_reached": false,
"code": "INVITATION_FAILED",
}
description: |
An example JSON error response for when some of the specified email addresses
have existing Zulip accounts.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Insufficient permission",
"result": "error",
}
description: |
An example JSON error response for when the user doesn't have permission
to send invitations.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "You must specify at least one email address.",
"result": "error",
}
description: |
An example JSON error response for when no email address is specified.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid channel ID 11. No invites were sent.",
"result": "error",
}
description: |
An example JSON error response for when any of the specified channels
does not exist or the user does not have permission to access one of
the targeted channels.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "You do not have permission to subscribe other users to channels.",
"result": "error",
}
description: |
An example JSON error response for when the user doesn't have permission
to subscribe other users to channels and `stream_ids` is not empty.
/invites/multiuse:
post:
operationId: create-invite-link
summary: Create a reusable invitation link
tags: ["invites"]
description: |
Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
which can be used to invite new users to the organization.
**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin
users [with permission](/help/restrict-account-creation#change-who-can-send-invitations)
to use this endpoint. Previously, it was restricted to administrators only.
In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
parameter was removed and replaced by `invite_expires_in_minutes`.
In Zulip 5.0 (feature level 117), added support for passing `null` as
the `invite_expires_in_days` parameter to request an invitation that never
expires.
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
added which specified the number of days before the invitation would expire.
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
invite_expires_in_minutes:
$ref: "#/components/schemas/InviteExpirationParameter"
invite_as:
$ref: "#/components/schemas/InviteRoleParameter"
stream_ids:
description: |
A list containing the [IDs of the channels](/api/get-stream-id) that the
newly created user will be automatically subscribed to if the invitation
is accepted, in addition to any default channels that the new user may
be subscribed to based on the `include_realm_default_subscriptions`
parameter.
This list must be empty if the current user has the unlikely
configuration of being able to create reusable invitation links while
lacking permission to [subscribe other users to
channels][can-subscribe-others].
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
type: array
items:
type: integer
default: []
example: [1, 10]
include_realm_default_subscriptions:
description: |
Boolean indicating whether the newly created user should be subscribed
to the [default channels][default-channels] for the organization.
Note that this parameter can be `true` even if the current user does
not generally have permission to [subscribe other users to
channels][can-subscribe-others].
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
of Zulip behaved as though this parameter was always `false`; clients
needed to include the organization's default channels in the
`stream_ids` parameter for a newly created user to be automatically
subscribed to them.
[default-channels]: /help/set-default-channels-for-new-users
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
type: boolean
default: false
example: false
encoding:
invite_expires_in_minutes:
contentType: application/json
stream_ids:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
invite_link:
type: string
description: |
The URL of the [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
that was created by this request.
example:
{
"result": "success",
"msg": "",
"invite_link": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/",
}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Insufficient permission",
"result": "error",
}
description: |
An example JSON error response for when the user doesn't have permission
to send invitations.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid channel ID 11. No invites were sent.",
"result": "error",
}
description: |
An example JSON error response for when any of the specified channels
does not exist or the user does not have permission to access one of
the targeted channels.
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "You do not have permission to subscribe other users to channels.",
"result": "error",
}
description: |
An example JSON error response for when the user doesn't have permission
to subscribe other users to channels and `stream_ids` is not empty.
/invites/{invite_id}:
delete:
operationId: revoke-email-invite
summary: Revoke an email invitation
tags: ["invites"]
description: |
Revoke an [email invitation](/help/invite-new-users#send-email-invitations).
A user can only revoke [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
parameters:
- name: invite_id
in: path
description: |
The ID of the email invitation to be revoked.
schema:
type: integer
example: 1
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "No such invitation",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for an invalid email invitation ID:
/invites/multiuse/{invite_id}:
delete:
operationId: revoke-invite-link
summary: Revoke a reusable invitation link
tags: ["invites"]
description: |
Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).
A user can only revoke [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
**Changes**: Prior to Zulip 8.0 (feature level 209), only organization
administrators were able to create and revoke reusable invitation links.
parameters:
- name: invite_id
in: path
description: |
The ID of the reusable invitation link to be revoked.
schema:
type: integer
example: 1
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "No such invitation",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for an invalid invitation link ID:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invitation has already been revoked",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the invitation link has already
been revoked:
/invites/{invite_id}/resend:
post:
operationId: resend-email-invite
summary: Resend an email invitation
tags: ["invites"]
description: |
Resend an [email invitation](/help/invite-new-users#send-email-invitations).
A user can only resend [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
parameters:
- name: invite_id
in: path
description: |
The ID of the email invitation to be resent.
schema:
type: integer
example: 1
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "No such invitation",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for an invalid email invitation ID:
/register:
post:
operationId: register-queue
summary: Register an event queue
tags: ["real_time_events"]
description: |
This powerful endpoint can be used to register a Zulip "event queue"
(subscribed to certain types of "events", or updates to the messages
and other Zulip data the current user has access to), as well as to
fetch the current state of that data.
(`register` also powers the `call_on_each_event` Python API, and is
intended primarily for complex applications for which the more convenient
`call_on_each_event` API is insufficient).
This endpoint returns a `queue_id` and a `last_event_id`; these can be
used in subsequent calls to the
["events" endpoint](/api/get-events) to request events from
the Zulip server using long-polling.
The server will queue events for up to 10 minutes of inactivity.
After 10 minutes, your event queue will be garbage-collected. The
server will send `heartbeat` events every minute, which makes it easy
to implement a robust client that does not miss events unless the
client loses network connectivity with the Zulip server for 10 minutes
or longer.
Once the server garbage-collects your event queue, the server will
[return an error](/api/get-events#bad_event_queue_id-errors)
with a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from
the event queue. Your software will need to handle that error
condition by re-initializing itself (e.g. this is what triggers your
browser reloading the Zulip web app when your laptop comes back online
after being offline for more than 10 minutes).
When prototyping with this API, we recommend first calling `register`
with no `event_types` parameter to see all the available data from all
supported event types. Before using your client in production, you
should set appropriate `event_types` and `fetch_event_types` filters
so that your client only requests the data it needs. A few minutes
doing this often saves 90% of the total bandwidth and other resources
consumed by a client using this API.
See the [events system developer documentation][events-system-docs]
if you need deeper details about how the Zulip event queue system
works, avoids clients needing to worry about large classes of
potentially messy races, etc.
**Changes**: Before Zulip 7.0 (feature level 183), the
`realm_community_topic_editing_limit_seconds` property
was returned by the response. It was removed because it
had not been in use since the realm setting
`move_messages_within_stream_limit_seconds` was introduced
in feature level 162.
In Zulip 7.0 (feature level 163), the realm setting
`email_address_visibility` was removed. It was replaced by a [user
setting](/api/update-settings#parameter-email_address_visibility) with
a [realm user default][user-defaults], with the encoding of different
values preserved. Clients can support all versions by supporting the
current API and treating every user as having the realm's
`email_address_visibility` value.
[user-defaults]: /api/update-realm-user-settings-defaults#parameter-email_address_visibility
[events-system-docs]: https://zulip.readthedocs.io/en/latest/subsystems/events-system.html
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- event_types
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
apply_markdown:
description: |
Set to `true` if you would like the content to be rendered in HTML
format (otherwise the API will return the raw text that the user
entered)
type: boolean
default: false
example: true
client_gravatar:
description: |
Whether the client supports computing gravatars URLs. If
enabled, `avatar_url` will be included in the response only
if there is a Zulip avatar, and will be `null` for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The `client_gravatar` field is set to `true` if
clients can compute their own gravatars.
The default value is `true` for authenticated requests and
`false` for [unauthenticated
requests](/help/public-access-option). Passing `true` in
an unauthenticated request is an error.
**Changes**: Before Zulip 6.0 (feature level 149), this
parameter was silently ignored and processed as though it
were `false` in unauthenticated requests.
type: boolean
example: false
include_subscribers:
description: |
Whether each returned channel object should include a `subscribers`
field containing a list of the user IDs of its subscribers.
(This may be significantly slower in organizations with
thousands of users subscribed to many channels.)
Passing `true` in an [unauthenticated
request](/help/public-access-option) is an error.
**Changes**: Before Zulip 6.0 (feature level 149), this
parameter was silently ignored and processed as though it
were `false` in unauthenticated requests.
New in Zulip 2.1.0.
type: boolean
default: false
example: true
slim_presence:
description: |
If `true`, the `presences` object returned in the response will be keyed
by user ID and the entry for each user's presence data will be in the
modern format.
**Changes**: New in Zulip 3.0 (no feature level; API unstable).
type: boolean
default: false
example: true
event_types:
$ref: "#/components/schemas/Event_types"
all_public_streams:
$ref: "#/components/schemas/AllPublicChannels"
client_capabilities:
description: |
Dictionary containing details on features the client supports that are
relevant to the format of responses sent by the server.
- `notification_settings_null`: Boolean for whether the
client can handle the current API with `null` values for
channel-level notification settings (which means the channel
is not customized and should inherit the user's global
notification settings for channel messages).
<br />
**Changes**: New in Zulip 2.1.0. In earlier Zulip releases,
channel-level notification settings were simple booleans.
- `bulk_message_deletion`: Boolean for whether the client's
handler for the `delete_message` event type has been
updated to process the new bulk format (with a
`message_ids`, rather than a singleton `message_id`).
Otherwise, the server will send `delete_message` events
in a loop.
<br />
**Changes**: New in Zulip 3.0 (feature level 13). This
capability is for backwards-compatibility; it will be
required in a future server release.
- `user_avatar_url_field_optional`: Boolean for whether the
client required avatar URLs for all users, or supports
using `GET /avatar/{user_id}` to access user avatars. If the
client has this capability, the server may skip sending a
`avatar_url` field in the `realm_user` at its sole discretion
to optimize network performance. This is an important optimization
in organizations with 10,000s of users.
<br />
**Changes**: New in Zulip 3.0 (feature level 18).
- `stream_typing_notifications`: Boolean for whether the client
supports channel typing notifications.
<br />
**Changes**: New in Zulip 4.0 (feature level 58). This capability is
for backwards-compatibility; it will be required in a
future server release.
- `user_settings_object`: Boolean for whether the client supports the modern
`user_settings` event type. If false, the server will additionally send the
legacy `update_global_notifications` and `update_display_settings` event
types.
<br />
**Changes**: New in Zulip 5.0 (feature level 89). This capability is for
backwards-compatibility; it will be removed in a future server release.
Because the feature level 89 API changes were merged together, clients can
safely make a request with this client capability and also request all three
event types (`user_settings`, `update_display_settings`,
`update_global_notifications`), and get exactly one copy of settings data on
any server version. Clients can then use the `zulip_feature_level` in the
`/register` response or the presence/absence of a `user_settings` key to
determine where to look for the data.
- `linkifier_url_template`: Boolean for whether the client accepts
[linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant
URL templates for linkifying matches. If false or unset, then the
`realm_linkifiers` array in the `/register` response will be empty
if present, and no `realm_linkifiers` [events][events-linkifiers]
will be sent to the client.
<br />
**Changes**: New in Zulip 7.0 (feature level 176). This capability
is for backwards-compatibility.
- `user_list_incomplete`: Boolean for whether the client supports not having an
incomplete user database. If true, then the `realm_users` array in the `register`
response will not include data for inaccessible users and clients of guest users will
not receive `realm_user op:add` events for newly created users that are not accessible
to the current user.
<br />
**Changes**: New in Zulip 8.0 (feature level 232). This
capability is for backwards-compatibility.
[help-linkifiers]: /help/add-a-custom-linkifier
[rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html
[events-linkifiers]: /api/get-events#realm_linkifiers
type: object
example: {"notification_settings_null": true}
fetch_event_types:
description: |
Same as the `event_types` parameter except that the values in
`fetch_event_types` are used to fetch initial data. If
`fetch_event_types` is not provided, `event_types` is used and if
`event_types` is not provided, this parameter defaults to `null`.
Event types not supported by the server are ignored, in order to simplify
the implementation of client apps that support multiple server versions.
type: array
items:
type: string
example: ["message"]
narrow:
$ref: "#/components/schemas/Narrow"
encoding:
apply_markdown:
contentType: application/json
client_gravatar:
contentType: application/json
include_subscribers:
contentType: application/json
slim_presence:
contentType: application/json
event_types:
contentType: application/json
all_public_streams:
contentType: application/json
client_capabilities:
contentType: application/json
fetch_event_types:
contentType: application/json
narrow:
contentType: application/json
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
queue_id:
type: string
nullable: true
description: |
The ID of the queue that has been allocated for your client.
Will be `null` only for unauthenticated access in realms that have
enabled the [public access option](/help/public-access-option).
last_event_id:
type: integer
description: |
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
zulip_feature_level:
type: integer
description: |
The server's current [Zulip feature level](/api/changelog).
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
in the endpoint's response. Previously, it was only present if
`event_types` included `zulip_version`.
New in Zulip 3.0 (feature level 1).
zulip_version:
type: string
description: |
The server's version number. This is often a release version number,
like `2.1.7`. But for a server running a [version from Git][git-release],
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
**Changes**: As of Zulip 3.0 (feature level 3), this is always present
in the endpoint's response. Previously, it was only present if
`event_types` included `zulip_version`.
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
zulip_merge_base:
type: string
description: |
The `git merge-base` between `zulip_version` and official branches
in the public
[Zulip server and web app repository](https://github.com/zulip/zulip),
in the same format as `zulip_version`. This will equal
`zulip_version` if the server is not running a fork of the Zulip server.
This will be `""` if the server does not know its `merge-base`.
**Changes**: New in Zulip 5.0 (feature level 88).
alert_words:
type: array
description: |
Present if `alert_words` is present in `fetch_event_types`.
An array of strings, each an [alert word](/help/dm-mention-alert-notifications#alert-words)
that the current user has configured.
items:
type: string
custom_profile_fields:
type: array
description: |
Present if `custom_profile_fields` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains the
details of a single custom profile field that is available to users
in this Zulip organization. This must be combined with the custom profile
field values on individual user objects to display users' profiles.
items:
$ref: "#/components/schemas/CustomProfileField"
custom_profile_field_types:
type: object
description: |
Present if `custom_profile_fields` is present in `fetch_event_types`.
An array of objects; each object describes a type of custom profile field
that could be configured on this Zulip server. Each custom profile type
has an ID and the `type` property of a custom profile field is equal
to one of these IDs.
This attribute is only useful for clients containing UI for changing
the set of configured custom profile fields in a Zulip organization.
additionalProperties:
type: object
description: |
`{FIELD_TYPE}`: Dictionary which contains the details
of the field type with the field type as the name of the
property itself. The current supported field types are as follows:
- `SHORT_TEXT`
- `LONG_TEXT`
- `DATE` for date-based fields.
- `SELECT` for a list of options.
- `URL` for links.
- `EXTERNAL_ACCOUNT` for external accounts.
- `USER` for selecting a user for the field.
- `PRONOUNS` for a short text field with convenient typeahead for one's preferred pronouns.
**Changes**: `PRONOUNS` type added in Zulip 6.0 (feature level 151).
additionalProperties: false
properties:
id:
type: integer
description: |
The ID of the custom profile field type.
name:
type: string
description: |
The name of the custom profile field type.
realm_date_created:
type: integer
description: |
The UNIX timestamp (UTC) for when the organization was
created.
**Changes**: New in Zulip 8.0 (feature level 203).
demo_organization_scheduled_deletion_date:
type: integer
description: |
Present if the realm is a demo organization.
The UNIX timestamp (UTC) when the demo organization will be
automatically deleted. Clients should use this to display a
prominent warning to the user that the organization will be
deleted at the indicated time.
**Changes**: New in Zulip 5.0 (feature level 94).
drafts:
type: array
description: |
An array containing draft objects for the user. These drafts are being
stored on the backend for the purpose of syncing across devices. This
array will be empty if `enable_drafts_synchronization` is set to `false`.
items:
$ref: "#/components/schemas/Draft"
onboarding_steps:
type: array
description: |
Present if `onboarding_steps` is present in `fetch_event_types`.
An array of dictionaries, where each dictionary contains details about
a single onboarding step that should be shown to the user.
We expect that only official Zulip clients will interact with this data.
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported, and the `type` field in these objects did not
exist as all onboarding steps were implicitly hotspots.
items:
$ref: "#/components/schemas/OnboardingStep"
max_message_id:
type: integer
deprecated: true
description: |
Present if `message` is present in `fetch_event_types`.
The highest message ID among all messages the user has received as of the
moment of this request.
**Deprecated**: This field may be removed in future versions as it no
longer has a clear purpose. Clients wishing to fetch the latest messages
should pass `"anchor": "latest"` to `GET /messages`.
max_stream_name_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a channel name, in Unicode code
points. Clients should use this property rather than hardcoding
field sizes.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this required `stream` in `fetch_event_types`, was called
`stream_name_max_length`, and always had a value of 60.
max_stream_description_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a channel description, in Unicode
code points. Clients should use this property rather than hardcoding
field sizes.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this required `stream` in `fetch_event_types`, was called
`stream_description_max_length`, and always had a value of 1024.
max_topic_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a topic, in Unicode code points.
Clients should use this property rather than hardcoding field
sizes.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this property always had a value of 60.
max_message_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a message, in Unicode code points.
Clients should use this property rather than hardcoding field
sizes.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this property always had a value of 10000.
server_presence_ping_interval_seconds:
type: integer
description: |
For clients implementing the [presence](/api/get-presence) system,
the time interval the client should use for sending presence requests
to the server (and thus receive presence updates from the server).
It is important for presence implementations to use both this and
`server_presence_offline_threshold_seconds` correctly, so that a Zulip
server can change these values to manage the trade-off between load and
freshness of presence data.
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 60
for older Zulip servers, since that's the value that was hardcoded in the
Zulip mobile apps prior to this parameter being introduced.
server_presence_offline_threshold_seconds:
type: integer
description: |
How old a presence timestamp for a given user can be before the user
should be displayed as offline by clients displaying Zulip presence
data. See the related `server_presence_ping_interval_seconds` for details.
**Changes**: New in Zulip 7.0 (feature level 164). Clients should use 140
for older Zulip servers, since that's the value that was hardcoded in the
Zulip client apps prior to this parameter being introduced.
server_typing_started_expiry_period_milliseconds:
type: integer
description: |
For clients implementing [typing notifications](/api/set-typing-status)
protocol, the time interval in milliseconds that the client should wait
for additional [typing start](/api/get-events#typing-start) events from
the server before removing an active typing indicator.
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 15000
for older Zulip servers, since that's the value that was hardcoded in the
Zulip apps prior to this parameter being introduced.
server_typing_stopped_wait_period_milliseconds:
type: integer
description: |
For clients implementing [typing notifications](/api/set-typing-status)
protocol, the time interval in milliseconds that the client should wait
when a user stops interacting with the compose UI before sending a stop
notification to the server.
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 5000
for older Zulip servers, since that's the value that was hardcoded in the
Zulip apps prior to this parameter being introduced.
server_typing_started_wait_period_milliseconds:
type: integer
description: |
For clients implementing [typing notifications](/api/set-typing-status)
protocol, the time interval in milliseconds that the client should use
to send regular start notifications to the server to indicate that the
user is still actively interacting with the compose UI.
**Changes**: New in Zulip 8.0 (feature level 204). Clients should use 10000
for older Zulip servers, since that's the value that was hardcoded in the
Zulip apps prior to this parameter being introduced.
scheduled_messages:
type: array
description: |
Present if `scheduled_messages` is present in `fetch_event_types`.
An array of all undelivered scheduled messages by the user.
**Changes**: New in Zulip 7.0 (feature level 179).
items:
$ref: "#/components/schemas/ScheduledMessage"
muted_topics:
type: array
deprecated: true
description: |
Present if `muted_topics` is present in `fetch_event_types`.
Array of tuples, where each tuple describes a muted topic.
The first element of the tuple is the channel name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
**Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting
with this version, `muted_topics` will only be present in the
response if the `user_topic` object, which generalizes and replaces
this field, is not explicitly requested via `fetch_event_types`.
Before Zulip 3.0 (feature level 1), the `muted_topics`
array objects were 2-item tuples and did not include the timestamp
information for when the topic was muted.
items:
type: array
items:
oneOf:
- type: string
- type: integer
muted_users:
type: array
description: |
Present if `muted_users` is present in `fetch_event_types`.
A list of dictionaries where each dictionary describes
a [muted user](/api/mute-user).
**Changes**: New in Zulip 4.0 (feature level 48).
items:
type: object
additionalProperties: false
description: |
Object containing the user ID and timestamp of a muted user.
properties:
id:
type: integer
description: |
The ID of the muted user.
timestamp:
type: integer
description: |
An integer UNIX timestamp representing when the user was muted.
presences:
type: object
description: |
Present if `presence` is present in `fetch_event_types`.
A dictionary where each entry describes the presence details of a
user in the Zulip organization.
The format of the entry (modern or legacy) depends on the value of
[`slim_presence`](#parameter-slim_presence).
Users who have been offline for multiple weeks may not appear in this object.
additionalProperties:
type: object
description: |
Will be one of these two formats (modern or legacy) for user
presence data:
oneOf:
- $ref: "#/components/schemas/ModernPresenceFormat"
- type: object
description: |
`{user_email}`: Presence data (legacy format) for the user with
the specified Zulip API email.
additionalProperties:
$ref: "#/components/schemas/LegacyPresenceFormat"
presence_last_update_id:
type: integer
description: |
Present if `presence` is present in `fetch_event_types`.
Provides the `last_update_id` value of the latest presence data fetched by
the server and included in the response in `presences`. This can be used
as the value of the `presence_last_update_id` parameter when polling
for presence data at the [/users/me/presence](/api/update-presence) endpoint
to tell the server to only fetch the relevant newer data in order to skip
redundant already-known presence information.
**Changes**: New in Zulip 9.0 (feature level 263).
server_timestamp:
type: number
description: |
Present if `presence` is present in `fetch_event_types`.
The time when the server fetched the
`presences` data included in the response.
Matches the similar field in presence
responses.
**Changes**: New in Zulip 5.0 (feature level 70).
realm_domains:
type: array
description: |
Present if `realm_domains` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a domain within
which users can join the organization without and invitation.
items:
$ref: "#/components/schemas/RealmDomain"
realm_emoji:
description: |
Present if `realm_emoji` is present in `fetch_event_types`.
A dictionary of objects where each object describes a custom
emoji that has been uploaded in this Zulip organization.
type: object
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
realm_linkifiers:
type: array
description: |
Present if `realm_linkifiers` is present in `fetch_event_types`.
An ordered array of objects where each object describes a single
[linkifier](/help/add-a-custom-linkifier).
The order of the array reflects the order that each
linkifier should be processed when linkifying messages
and topics. By default, new linkifiers are ordered
last. This order can be modified with [`PATCH
/realm/linkifiers`](/api/reorder-linkifiers).
Clients will receive an empty array unless the event queue is
registered with the client capability `{"linkifier_url_template": true}`.
See [`client_capabilities`](/api/register-queue#parameter-client_capabilities)
parameter for how this can be specified.
**Changes**: Before Zulip 7.0 (feature level 176), the
`linkifier_url_template` client capability was not required. The
requirement was added because linkifiers were updated to contain
a URL template instead of a URL format string, which was a not
backwards-compatible change.
New in Zulip 4.0 (feature level 54). Clients can access this data for
servers on earlier feature levels via the legacy `realm_filters` property.
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The [Python regular expression](https://docs.python.org/3/howto/regex.html)
pattern which represents the pattern that should be linkified on matching.
url_template:
type: string
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL
template with which the pattern matching string should be linkified.
**Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`,
which contained a URL format string.
id:
type: integer
description: |
The ID of the linkifier.
realm_filters:
type: array
deprecated: true
items:
type: array
items:
oneOf:
- type: integer
- type: string
description: |
Legacy property for [linkifiers](/help/add-a-custom-linkifier).
Present if `realm_filters` is present in `fetch_event_types`.
When present, this is always an empty array.
**Changes**: Prior to Zulip 7.0 (feature level 176), this was
an array of tuples, where each tuple described a linkifier. The first
element of the tuple was a string regex pattern which represented the
pattern to be linkified on matching, for example `"#(?P<id>[123])"`.
The second element was a URL format string that the pattern should be
linkified with. A URL format string for the above example would be
`"https://realm.com/my_realm_filter/%(id)s"`. And the third element
was the ID of the realm filter.
**Deprecated** in Zulip 4.0 (feature level 54), replaced by the
`realm_linkifiers` key.
realm_playgrounds:
type: array
items:
$ref: "#/components/schemas/RealmPlayground"
description: |
Present if `realm_playgrounds` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a
[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.
**Changes**: New in Zulip 4.0 (feature level 49).
realm_user_groups:
type: array
items:
$ref: "#/components/schemas/UserGroup"
description: |
Present if `realm_user_groups` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a
[user group](/help/user-groups) in the Zulip organization.
realm_bots:
type: array
items:
$ref: "#/components/schemas/Bot"
description: |
Present if `realm_bot` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a bot that the
current user can administer. If the current user is an organization
administrator, this will include all bots in the organization. Otherwise,
it will only include bots owned by the user (either because the user created
the bot or an administrator transferred the bot's ownership to the user).
realm_embedded_bots:
type: array
items:
type: object
additionalProperties: false
description: |
Object containing details of an embedded bot. Embedded bots are an experimental
feature not enabled in production yet.
properties:
name:
type: string
description: |
The name of the bot.
config:
$ref: "#/components/schemas/BotConfiguration"
description: |
Present if `realm_embedded_bots` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes an type of embedded
bot that is available to be configured on this Zulip server.
Clients only need these data if they contain UI for creating or administering bots.
realm_incoming_webhook_bots:
description: |
Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a type of incoming webhook
integration that is available to be configured on this Zulip server.
Clients only need these data if they contain UI for creating or administering bots.
type: array
items:
type: object
additionalProperties: false
description: |
Object containing details of the bot.
properties:
name:
type: string
description: |
A machine-readable unique name identifying the integration, all-lower-case without
spaces.
display_name:
type: string
description: |
A human-readable display name identifying the integration that this bot implements,
intended to be used in menus for selecting which integration to create.
**Changes**: New in Zulip 8.0 (feature level 207).
all_event_types:
type: array
items:
type: string
nullable: true
description: |
For incoming webhook integrations that support the Zulip server filtering incoming
events, the list of event types supported by it.
A null value will be present if this incoming webhook integration doesn't support
such filtering.
**Changes**: New in Zulip 8.0 (feature level 207).
config:
$ref: "#/components/schemas/BotConfiguration"
recent_private_conversations:
description: |
Present if `recent_private_conversations` is present in `fetch_event_types`.
An array of dictionaries containing data on all direct message and group direct message
conversations that the user has received (or sent) messages in, organized by
conversation. This data set is designed to support UI elements such as the
"Direct messages" widget in the web application showing recent direct message
conversations that the user has participated in.
"Recent" is defined as the server's discretion; the original implementation
interpreted that as "the 1000 most recent direct messages the user received".
type: array
items:
type: object
additionalProperties: false
description: |
Object describing a single recent direct conversation in the user's history.
properties:
max_message_id:
type: integer
description: |
The highest message ID of the conversation, intended to support sorting
the conversations by recency.
user_ids:
type: array
items:
type: integer
description: |
The list of users other than the current user in the direct message
conversation. This will be an empty list for direct messages sent to
oneself.
subscriptions:
type: array
items:
$ref: "#/components/schemas/Subscriptions"
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes the properties
of a channel the user is subscribed to (as well as that user's
personal per-channel settings).
**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).
unsubscribed:
type: array
items:
$ref: "#/components/schemas/Subscriptions"
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes one of the
channels the user has unsubscribed from but was previously subscribed to
along with the subscription details.
Unlike `never_subscribed`, the user might have messages in their personal
message history that were sent to these 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).
never_subscribed:
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicChannelBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
creator_id:
nullable: true
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
can_remove_subscribers_group: {}
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the channel per week, as
estimated based on recent weeks, rounded to the nearest integer.
If `null`, the channel was recently created and there is
insufficient data to estimate the average traffic.
subscribers:
type: array
items:
type: integer
description: |
A list of user IDs of users who are subscribed
to the channel. Included only if `include_subscribers` is `true`.
If a user is not allowed to know the subscribers for
a channel, we will send an empty array. API authors
should use other data to determine whether users like
guest users are forbidden to know the subscribers.
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes one of the
channels that is visible to the user and the user has never been subscribed
to.
Important for clients containing UI where one can browse channels to subscribe
to.
unread_msgs:
type: object
description: |
Present if `message` and `update_message_flags` are both present in
`event_types`.
A set of data structures describing the conversations containing
the 50000 most recent unread messages the user has received. This will usually
contain every unread message the user has received, but clients should support
users with even more unread messages (and not hardcode the number 50000).
additionalProperties: false
properties:
count:
type: integer
description: |
The total number of unread messages to display. This includes one-on-one and group
direct messages, as well as channel messages that are not [muted](/help/mute-a-topic).
**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow
topic features were not handled correctly in calculating this field.
pms:
type: array
description: |
An array of objects where each object contains details of unread
one-on-one direct messages with a specific user.
Note that it is possible for a message that the current user sent
to the specified user to be marked as unread and thus appear here.
items:
type: object
additionalProperties: false
properties:
other_user_id:
type: integer
description: |
The user ID of the other participant in this one-on-one direct
message conversation. Will be the current user's ID for messages
that they sent in a one-on-one direct message conversation with
themself.
**Changes**: New in Zulip 5.0 (feature level 119), replacing
the less clearly named `sender_id` field.
sender_id:
deprecated: true
type: integer
description: |
Old name for the `other_user_id` field. Clients should access
this field in Zulip server versions that do not yet support
`other_user_id`.
**Changes**: Deprecated in Zulip 5.0 (feature level 119).
We expect to provide a next version of the full `unread_msgs`
API before removing this legacy name.
unread_message_ids:
type: array
description: |
The message IDs of the recent unread direct messages sent
by either user in this one-on-one direct message conversation,
sorted in ascending order.
items:
type: integer
streams:
type: array
description: |
An array of dictionaries where each dictionary contains details of all
unread messages of a single subscribed channel. This includes muted channels
and muted topics, even though those messages are excluded from `count`.
**Changes**: Prior to Zulip 5.0 (feature level 90), these objects
included a `sender_ids` property, which listed the set of IDs of
users who had sent the unread messages.
items:
type: object
additionalProperties: false
properties:
topic:
type: string
description: |
The topic under which the messages were sent.
stream_id:
type: integer
description: |
The ID of the channel to which the messages were sent.
unread_message_ids:
type: array
description: |
The message IDs of the recent unread messages sent in this channel,
sorted in ascending order.
items:
type: integer
huddles:
type: array
description: |
An array of objects where each object contains details of unread
group direct messages with a specific group of users.
items:
type: object
additionalProperties: false
properties:
user_ids_string:
type: string
description: |
A string containing the IDs of all users in the group
direct message conversation, including the current user,
separated by commas and sorted numerically; for example:
`"1,2,3"`.
unread_message_ids:
type: array
description: |
The message IDs of the recent unread messages which have been sent in
this group direct message conversation, sorted in ascending order.
items:
type: integer
mentions:
type: array
description: |
Array containing the IDs of all unread messages in which the user was
mentioned directly, and unread [non-muted](/help/mute-a-topic) messages
in which the user was mentioned through a wildcard.
**Changes**: Before Zulip 8.0 (feature level 213), the unmute and follow
topic features were not handled correctly in calculating this field.
items:
type: integer
old_unreads_missing:
type: boolean
description: |
Whether this data set was truncated because the user has too many
unread messages. When truncation occurs, only the most recent
`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered
when forming this response. When `true`, we recommend that clients
display a warning, as they are likely to produce erroneous results
until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`
unread messages.
**Changes**: New in Zulip 4.0 (feature level 44).
starred_messages:
type: array
items:
type: integer
description: |
Present if `starred_messages` is present in `fetch_event_types`.
Array containing the IDs of all messages which have been
[starred](/help/star-a-message) by the user.
streams:
type: array
items:
$ref: "#/components/schemas/BasicChannel"
description: |
Present if `stream` is present in `fetch_event_types`.
Array of dictionaries where each dictionary contains details about
a single channel in the organization that is visible to the user.
For organization administrators, this will include all private channels
in the organization.
**Changes**: As of Zulip 8.0 (feature level 205), this will include all
web-public channels in the organization as well.
realm_default_streams:
type: array
items:
$ref: "#/components/schemas/DefaultChannel"
description: |
Present if `default_streams` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains details
about a single [default channel](/help/set-default-channels-for-new-users)
for the Zulip organization.
realm_default_stream_groups:
type: array
items:
$ref: "#/components/schemas/DefaultChannelGroup"
description: |
Present if `default_stream_groups` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains details
about a single default channel group configured for this
Zulip organization.
Default channel groups are an experimental feature.
stop_words:
type: array
items:
type: string
description: |
Present if `stop_words` is present in `fetch_event_types`.
An array containing the stop words used by the Zulip server's
full-text search implementation. Useful for showing helpful
error messages when a search returns limited results because
a stop word in the query was ignored.
user_status:
type: object
description: |
Present if `user_status` is present in `fetch_event_types`.
A dictionary which contains the [status](/help/status-and-availability)
of all users in the Zulip organization who have set a status.
**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).
Previously, Zulip did not support emoji associated with statuses.
additionalProperties:
allOf:
- description: |
`{user_id}`: Object containing the status details of a user
with the key of the object being the ID of the user.
- $ref: "#/components/schemas/UserStatus"
user_settings:
type: object
description: |
Present if `user_settings` is present in `fetch_event_types`.
A dictionary containing the user's personal settings.
**Changes**: New in Zulip 5.0 (feature level 89). Previously,
these settings appeared in the top-level object, where they are
available for clients without the `user_settings_object` client
capability for backwards-compatibility.
additionalProperties: false
properties:
twenty_four_hour_time:
type: boolean
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
dense_mode:
type: boolean
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
web_mark_read_on_scroll_policy:
type: integer
description: |
Whether or not to mark messages as read when the user scrolls through their
feed.
- 1 - Always
- 2 - Only in conversation views
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
way for the user to configure this behavior on the web, and the Zulip web and
desktop apps behaved like the "Always" setting when marking messages as read.
web_channel_default_view:
type: integer
description: |
Web/desktop app setting controlling the default navigation
behavior when clicking on a channel link.
- 1 - Top topic in the channel
- 2 - Channel feed
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
was not configurable, and every user had the "Channel feed" behavior.
starred_message_counts:
type: boolean
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
receives_typing_notifications:
type: boolean
description: |
Whether the user is configured to receive typing notifications from
other users. The server will only deliver typing notifications events
to users who for whom this is enabled.
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
only options to disable sending typing notifications.
fluid_layout_width:
type: boolean
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent conversations) on wide screens.
high_contrast_mode:
type: boolean
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
web_font_size_px:
description: |
User-configured primary `font-size` for the web application, in pixels.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
only adjustable via browser zoom. Note that this setting was not fully
implemented at this feature level.
type: integer
example: 14
web_line_height_percent:
description: |
User-configured primary `line-height` for the web application, in percent, so a
value of 120 represents a `line-height` of 1.2.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
not user-configurable. Note that this setting was not fully implemented at this
feature level.
type: integer
example: 122
color_scheme:
type: integer
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
translate_emoticons:
type: boolean
description: |
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
in messages the user sends.
display_emoji_reaction_users:
type: boolean
description: |
Whether to display the names of reacting users on a message.
When enabled, clients should display the names of reacting
users, rather than a count, for messages with few total
reactions. The ideal cutoff may depend on the space
available for displaying reactions; the official web
application displays names when 3 or fewer total reactions
are present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
default_language:
type: string
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
web_home_view:
type: string
description: |
The [home view](/help/configure-home-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent conversations view
- "inbox" - Inbox view
- "all_messages" - Combined feed view
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
called `default_view`, which was new in Zulip 4.0 (feature level 42).
web_escape_navigates_to_home_view:
type: boolean
description: |
Whether the escape key navigates to the
[configured home view](/help/configure-home-view).
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
was called `escape_navigates_to_default_view`, which was new in Zulip
5.0 (feature level 107).
left_side_userlist:
type: boolean
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
emojiset:
type: string
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
demote_inactive_streams:
type: integer
description: |
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
user_list_style:
type: integer
description: |
The style selected by the user for the right sidebar user list.
- 1 - Compact
- 2 - With status
- 3 - With avatar and status
**Changes**: New in Zulip 6.0 (feature level 141).
web_animate_image_previews:
type: string
description: |
Controls how animated images should be played in the message feed in the web/desktop application.
- "always" - Always play the animated images in the message feed.
- "on_hover" - Play the animated images on hover over them in the message feed.
- "never" - Never play animated images in the message feed.
**Changes**: New in Zulip 9.0 (feature level 275).
web_stream_unreads_count_display_policy:
type: integer
description: |
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
Channels that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All channels
- 2 - Unmuted channels and topics
- 3 - No channels
**Changes**: New in Zulip 8.0 (feature level 210).
timezone:
type: string
description: |
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
enter_sends:
type: boolean
description: |
Whether the user setting for [sending on pressing Enter](/help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message)
in the compose box is enabled.
enable_drafts_synchronization:
type: boolean
description: |
A boolean parameter to control whether synchronizing drafts is enabled for
the user. When synchronization is disabled, all drafts stored in the server
will be automatically deleted from the server.
This does not do anything (like sending events) to delete local copies of
drafts stored in clients.
enable_stream_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for channel messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for channel messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for channel messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for channel messages.
notification_sound:
type: string
description: |
Notification sound name.
enable_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for direct messages and @-mentions.
enable_sounds:
type: boolean
description: |
Enable audible desktop notifications for direct messages and
@-mentions.
enable_followed_topic_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_email_notifications:
type: boolean
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_push_notifications:
type: boolean
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
email_notifications_batching_period_seconds:
type: integer
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
enable_offline_email_notifications:
type: boolean
description: |
Enable email notifications for direct messages and @-mentions received
when the user is offline.
enable_offline_push_notifications:
type: boolean
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is offline.
enable_online_push_notifications:
type: boolean
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is online.
enable_digest_emails:
type: boolean
description: |
Enable digest emails when the user is away.
enable_marketing_emails:
type: boolean
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
enable_login_emails:
type: boolean
description: |
Enable email notifications for new logins to account.
message_content_in_email_notifications:
type: boolean
description: |
Include the message's content in email notifications for new messages.
pm_content_in_desktop_notifications:
type: boolean
description: |
Include content of direct messages in desktop notifications.
wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
enable_followed_topic_wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
should send notifications like a personal mention.
**Changes**: New in Zulip 8.0 (feature level 189).
desktop_icon_count_display:
type: integer
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unread messages
- 2 - DMs, mentions, and followed topics
- 3 - DMs and mentions
- 4 - None
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,
and followed topics` option, renumbering the options to insert it in
order.
realm_name_in_email_notifications_policy:
type: integer
description: |
Whether to [include organization name in subject of message notification
emails](/help/email-notifications#include-organization-name-in-subject-line).
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
previous `realm_name_in_notifications` boolean;
`true` corresponded to `Always`, and `false` to `Never`.
automatically_follow_topics_policy:
type: integer
description: |
Which [topics to follow automatically](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
automatically_unmute_topics_in_muted_streams_policy:
type: integer
description: |
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
automatically_follow_topics_where_mentioned:
type: boolean
description: |
Whether the server will automatically mark the user as following
topics where the user is mentioned.
**Changes**: New in Zulip 8.0 (feature level 235).
presence_enabled:
type: boolean
description: |
Display the presence status to other users when online.
available_notification_sounds:
type: array
items:
type: string
description: |
Array containing the names of the notification sound options
supported by this Zulip server. Only relevant to support UI
for configuring notification sounds.
emojiset_choices:
description: |
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
send_private_typing_notifications:
type: boolean
description: |
Whether the user has chosen to send [typing
notifications](/help/typing-notifications)
when composing direct messages. The client should send typing
notifications for direct messages if and only if this setting is enabled.
**Changes**: New in Zulip 5.0 (feature level 105).
send_stream_typing_notifications:
type: boolean
description: |
Whether the user has chosen to send [typing
notifications](/help/typing-notifications)
when composing channel messages. The client should send typing
notifications for channel messages if and only if this setting is enabled.
**Changes**: New in Zulip 5.0 (feature level 105).
send_read_receipts:
type: boolean
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
email_address_visibility:
$ref: "#/components/schemas/EmailAddressVisibility"
web_navigate_to_sent_message:
type: boolean
description: |
Web/desktop app setting for whether the user's view should
automatically go to the conversation where they sent a message.
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
this behavior was not configurable.
user_topics:
type: array
description: |
Present if `user_topic` is present in `fetch_event_types`.
**Changes**: New in Zulip 6.0 (feature level 134), deprecating and
replacing the previous `muted_topics` structure.
items:
type: object
description: |
Object describing the user's configuration for a given topic.
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The ID of the channel to which the topic belongs.
topic_name:
type: string
description: |
The name of the topic.
last_updated:
type: integer
description: |
An integer UNIX timestamp representing when the user-topic
relationship was changed.
visibility_policy:
type: integer
description: |
An integer indicating the user's visibility configuration for
the topic.
- 1 = Muted. Used to record [muted topics](/help/mute-a-topic).
- 2 = Unmuted. Used to record [unmuted topics](/help/mute-a-topic).
- 3 = Followed. Used to record [followed topics](/help/follow-a-topic).
**Changes**: In Zulip 7.0 (feature level 219), added followed as
a visibility policy option.
In Zulip 7.0 (feature level 170), added unmuted as a visibility
policy option.
has_zoom_token:
type: boolean
description: |
Present if `video_calls` is present in `fetch_event_types`.
A boolean which signifies whether the user has a zoom token and has thus completed
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
to know whether initiating Zoom OAuth is required before creating a Zoom call.
giphy_api_key:
type: string
description: |
Present if `giphy` is present in `fetch_event_types`.
GIPHY's client-side SDKs needs this API key to use the GIPHY API.
GIPHY API keys are not secret (their main purpose appears to be
allowing GIPHY to block a problematic app). Please don't use our API
key for an app unrelated to Zulip.
Developers of clients should also read the
[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)
before using this API key.
**Changes**: Added in Zulip 4.0 (feature level 47).
enable_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_digest_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_login_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_marketing_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
email_notifications_batching_period_seconds:
deprecated: true
type: integer
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_offline_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_offline_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_online_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_sounds:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_stream_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_stream_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_stream_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_stream_audible_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
wildcard_mentions_notify:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
message_content_in_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
notification_sound:
deprecated: true
type: string
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
pm_content_in_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
desktop_icon_count_display:
deprecated: true
type: integer
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
realm_name_in_email_notifications_policy:
deprecated: true
type: integer
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: In Zulip 7.0 (feature level 168), replaced previous
`realm_name_in_notifications` global notifications setting with
`realm_name_in_email_notifications_policy`.
**Deprecated** since Zulip 5.0 (feature level 89); both
`realm_name_in_notifications` and the newer
`realm_name_in_email_notifications_policy` are deprecated. Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
presence_enabled:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
available_notification_sounds:
deprecated: true
type: array
items:
type: string
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
[`client_capabilities`][capabilities] when registering the event queue.
Array containing the names of the notification sound options supported by
this Zulip server. Only relevant to support UI for configuring notification
sounds.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
color_scheme:
deprecated: true
type: integer
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
The color scheme selected by the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
default_language:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
The default language chosen by the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
demote_inactive_streams:
deprecated: true
type: integer
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen to demote inactive channels.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
dense_mode:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has switched on dense mode. Dense mode is an experimental
feature that is only available in development environments.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
emojiset:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
The name of the emoji set that the user has chosen.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
enable_drafts_synchronization:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether drafts synchronization is enabled for the user. If disabled,
clients will receive an error when trying to use the `drafts` endpoints.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
New in Zulip 5.0 (feature level 87).
[capabilities]: /api/register-queue#parameter-client_capabilities
fluid_layout_width:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen for the layout width to be fluid.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
web_home_view:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
The [home view](/help/configure-home-view) in Zulip, represented
as the URL suffix after `#` to be rendered when Zulip loads.
Currently supported values are `all_messages` and `recent_topics`.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
called `default_view`, which was new in Zulip 4.0 (feature level 42).
**Deprecated** in Zulip 5.0 (feature level 89). Clients connecting to newer
servers should declare the `user_settings_object` client capability and
access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
high_contrast_mode:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether has switched on high contrast mode.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
left_side_userlist:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen for the userlist to be displayed
on the left side of the screen (for desktop app and web app) in narrow
windows.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
starred_message_counts:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen the number of starred messages to
be displayed similar to unread counts.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
timezone:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
The time zone configured for the user. This is used primarily to display
the user's time zone to other users.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
translate_emoticons:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen for emoticons to be translated into emoji
in the Zulip compose box.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
twenty_four_hour_time:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user has chosen a twenty four hour time display (true)
or a twelve hour one (false).
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
receives_typing_notifications:
type: boolean
description: |
Whether the user is configured to receive typing notifications from other
users. The server will only deliver typing notifications events to users who
for whom this is enabled.
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
only options to disable sending typing notifications.
enter_sends:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Whether the user setting for [sending on pressing Enter][set-enter-send]
in the compose box is enabled.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
Prior to Zulip 5.0 (feature level 84), this field was present
in response if `realm_user` was present in `fetch_event_types`, not
`update_display_settings`.
[capabilities]: /api/register-queue#parameter-client_capabilities
[set-enter-send]: /help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message
emojiset_choices:
deprecated: true
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their [`client_capabilities`][capabilities] when registering the event queue.
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
[capabilities]: /api/register-queue#parameter-client_capabilities
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
realm_add_custom_emoji_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can upload new custom emoji
in this organization.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
**Changes**: New in Zulip 5.0 (feature level 85) replacing the
previous `realm_add_emoji_by_admins_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_allow_edit_history:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization is configured to allow users to access
[message edit history](/help/view-a-messages-edit-history).
realm_can_delete_any_message_group:
allOf:
- description: |
Present if `realm` is present in `fetch_event_types`.
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to delete any message in the organization.
**Changes**: New in Zulip 10.0 (feature level 281). Previously, this
permission was limited to administrators only and was uneditable.
- $ref: "#/components/schemas/GroupSettingValue"
realm_delete_own_message_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] defining which users can delete
messages that they had sent.
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Admins and moderators only
- 5 = Everyone
**Changes**: New in Zulip 5.0 (feature level 101), replacing the
previous `allow_message_deleting` boolean;
`true` corresponded to `everyone`, and `false` to `admins only`.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_bot_creation_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create bot users in this organization.
realm_can_create_public_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create public
channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 264). Previously
`realm_create_public_stream_policy` field used to control the
permission to create public channels.
realm_can_create_private_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create private
channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 266). Previously
`realm_create_private_stream_policy` field used to control the
permission to create private channels.
realm_can_create_web_public_channel_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value](/api/group-setting-values) defining
the set of users who have permission to create web-public
channels in this organization.
This setting can only be set to `"role:moderators"`,
`"role:administrators"`, `"role:owners"` and
`"role:nobody"` system groups.
Has no effect and should not be displayed in settings UI
unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`
server-level setting enabled and the organization has enabled
the `enable_spectator_access` realm setting.
**Changes**: New in Zulip 10.0 (feature level 280). Previously
`realm_create_web_public_stream_policy` field used to control
the permission to create web-public channels.
realm_create_public_stream_policy:
type: integer
deprecated: true
description: |
Present if `realm` is present in `fetch_event_types`.
A deprecated representation of a superset of the users who
have permission to create public channels in the organization,
available for backwards-compatibility. Clients should use
`can_create_public_channel_group` instead.
It is an enum with the following possible values, corresponding
to roles/system groups:
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Admins and moderators only
**Changes**: Deprecated in Zulip 9.0 (feature level 264) and
replaced by `realm_can_create_public_channel_group`, which
supports finer resolution of configurations, resulting in this
property being inaccurate following that transition.
Before Zulip 5.0 (feature level 102), permission to create
channels was controlled by the `realm_create_stream_policy` setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_create_private_stream_policy:
type: integer
deprecated: true
description: |
Present if `realm` is present in `fetch_event_types`.
A deprecated representation of a superset of the users who
have permission to create private channels in the organization,
available for backwards-compatibility. Clients should use
`can_create_private_channel_group` instead.
It is an enum with the following possible values, corresponding
to roles/system groups:
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Admins and moderators only
**Changes**: Deprecated in Zulip 9.0 (feature level 266) and
replaced by `realm_can_create_private_channel_group`, which
supports finer resolution of configurations, resulting in this
property being inaccurate following that transition.
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create channels was controlled by the `realm_create_stream_policy` setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_create_web_public_stream_policy:
type: integer
deprecated: true
description: |
Present if `realm` is present in `fetch_event_types`.
A deprecated representation of a superset of the users who
have permission to create web-public channels in the
organization, available for backwards-compatibility. Clients
should use `can_create_web_public_channel_group` instead.
It is an enum with the following possible values, corresponding
to roles/system groups:
- 2 = Admins only
- 4 = Admins and moderators only
- 6 = Nobody
- 7 = Owners only
**Changes**: Deprecated in Zulip 10.0 (feature level 280) and
replaced by `realm_can_create_web_public_channel_group`, which
supports finer resolution of configurations, resulting in this
property being inaccurate following that transition.
**Changes**: Added in Zulip 5.0 (feature level 103).
[permission-level]: /api/roles-and-permissions#permission-levels
realm_invite_to_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add other users to channels in this organization.
realm_wildcard_mention_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for who can use wildcard mentions
in large channels.
- 1 = Any user can use wildcard mentions in large channels.
- 2 = Only members can use wildcard mentions in large channels.
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large channels.
- 5 = Only organization administrators can use wildcard mentions in large channels.
- 6 = Nobody can use wildcard mentions in large channels.
- 7 = Only organization administrators and moderators can use wildcard mentions in large channels.
All users will receive a warning/reminder when using
mentions in large channels, even when permitted to do so.
**Changes**: In Zulip 6.0 (feature level 133), channel administrators option removed.
In Zulip 4.0 (feature level 62), moderators option added.
New in Zulip 4.0 (feature level 33).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_default_language:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The [organization language][org-lang] for automated messages and invitation emails.
[org-lang]: /help/configure-organization-language
realm_description:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The description of the organization, used on login and registration pages.
realm_digest_emails_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
realm_disallow_disposable_email_addresses:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization disallows disposable email
addresses.
realm_email_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether users are allowed to change their own email address in this
organization. This is typically disabled for organizations that
synchronize accounts from LDAP or a similar corporate database.
realm_invite_required:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether an invitation is required to join this organization.
realm_invite_to_realm_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
[Policy][permission-level] for [who can invite new
users](/help/restrict-account-creation#change-who-can-send-invitations)
to join the organization:
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 6 = Nobody
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
previous `realm_invite_by_admins_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_create_multiuse_invite_group:
type: integer
description: |
The ID of the [user group](/api/get-user-groups) whose members are
allowed to create [reusable invitation
links](/help/invite-new-users#create-a-reusable-invitation-link)
to the organization.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
`"role:internet"` and `"role:owners"`.
**Changes**: New in Zulip 8.0 (feature level 209).
realm_move_messages_between_streams_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can move messages
from one channel to another.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 6 = Nobody
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 4.0 (feature level 56).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_inline_image_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization has been configured to enable
[previews of linked images](/help/image-video-and-website-previews).
realm_inline_url_embed_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization has been configured to enable
[previews of linked websites](/help/image-video-and-website-previews).
realm_mandatory_topics:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether [topics are required](/help/require-topics) for messages in this organization.
realm_message_retention_days:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The default [message retention policy](/help/message-retention-policy)
for this organization. It can have one special value:
- `-1` denoting that the messages will be retained forever for this realm, by default.
**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was
encoded as `null` instead of `-1`. Clients can correctly handle all
server versions by treating both `-1` and `null` as indicating
unlimited message retention.
realm_name:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The name of the organization, used in login pages etc.
realm_require_unique_names:
type: boolean
description: |
Indicates whether the organization is configured to require users
to have unique full names. If true, the server will reject attempts
to create a new user, or change the name of an existing user, where
doing so would lead to two users whose names are identical modulo
case and unicode normalization.
**Changes**: New in Zulip 9.0 (feature level 246). Previously, the Zulip
server could not be configured to enforce unique names.
realm_name_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their name
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
realm_avatar_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their avatar
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
realm_emails_restricted_to_domains:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
this organization are required to have an email
address in one of the `realm_domains` configured for the organization.
realm_send_welcome_emails:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether or not this organization is configured to send the standard Zulip
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
realm_message_content_allowed_in_email_notifications:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether notification emails in this organization are allowed to
contain Zulip the message content, or simply indicate that a new
message was sent.
realm_enable_spectator_access:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether web-public channels and related anonymous access APIs/features
are enabled in this organization.
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
[server setting][server-settings] is enabled on the Zulip
server. See also the `can_create_web_public_channel_group` realm
setting.
**Changes**: New in Zulip 5.0 (feature level 109).
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
realm_want_advertise_in_communities_directory:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has given permission to be advertised in the
Zulip [communities directory](/help/communities-directory).
Useful only to clients supporting changing this setting for the
organization.
Giving permission via this setting does not guarantee that an
organization will be listed in the Zulip communities directory.
**Changes**: New in Zulip 6.0 (feature level 129).
realm_video_chat_provider:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The configured [video call provider](/help/start-a-call) for the
organization.
- 0 = None
- 1 = Jitsi Meet
- 3 = Zoom
- 4 = BigBlueButton
**Changes**: None added as an option in Zulip 3.0 (feature level 1)
to disable video call UI.
realm_jitsi_server_url:
type: string
nullable: true
description: |
The URL of the custom Jitsi Meet server configured in this organization's
settings.
`null`, the default, means that the organization is using the should use the
server-level configuration, `server_jitsi_server_url`. A correct client
supporting only the modern API should use `realm_jitsi_server_url ||
server_jitsi_server_url` to create calls.
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this was only
available as a server-level configuration, which was available via the
`jitsi_server_url` field.
realm_giphy_rating:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The configured GIPHY rating for the organization.
**Changes**: New in Zulip 4.0 (feature level 55).
realm_waiting_period_threshold:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Members whose accounts have been created at least this many days ago
will be treated as [full members][calc-full-member]
for the purpose of settings that restrict access to new members.
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_digest_weekday:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The day of the week when the organization will send
its weekly digest email to inactive users.
realm_direct_message_initiator_group:
allOf:
- description: |
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to start a new direct message conversation
involving other non-bot users. Users who are outside this group and attempt
to send the first direct message to a given collection of recipient users
will receive an error, unless all other recipients are bots or the sender.
**Changes**: New in Zulip 9.0 (feature level 270).
Previously, access to send direct messages was controlled by the
`private_message_policy` realm setting, which supported values of
1 (enabled) and 2 (disabled).
- $ref: "#/components/schemas/GroupSettingValue"
realm_direct_message_permission_group:
allOf:
- description: |
A [group-setting value](/api/group-setting-values) defining the set of
users who have permission to fully use direct messages. Users outside
this group can only send direct messages to conversations where all the
recipients are in this group, are bots, or are the sender, ensuring that
every direct message conversation will be visible to at least one user in
this group.
**Changes**: New in Zulip 9.0 (feature level 270).
Previously, access to send direct messages was controlled by the
`private_message_policy` realm setting, which supported values of
1 (enabled) and 2 (disabled).
- $ref: "#/components/schemas/GroupSettingValue"
realm_user_group_edit_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The organization's [policy][permission-level] for
[who can manage user groups][user-group-permissions].
- 1 = All members can create and edit user groups
- 2 = Only organization administrators can create and edit user groups
- 3 = Only [full members][calc-full-member] can create and edit user groups.
- 4 = Only organization administrators and moderators can create and edit user groups.
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_default_code_block_language:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The default pygments language code to be used for code blocks in this
organization. If an empty string, no default has been set.
**Changes**: Prior to Zulip 8.0 (feature level 195), a server bug meant
that both `null` and an empty string could represent that no default was
set for this realm setting. Clients supporting older server versions
should treat either value (`null` or `""`) as no default being set.
realm_message_content_delete_limit_seconds:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be deleted
with this organization's
[message deletion policy](/help/restrict-message-editing-and-deletion).
Will not be 0. A `null` value means no limit: messages can be deleted
regardless of how long ago they were sent.
**Changes**: No limit was represented using the
special value `0` before Zulip 5.0 (feature level 100).
realm_authentication_methods:
type: object
additionalProperties:
$ref: "#/components/schemas/RealmAuthenticationMethod"
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary of authentication method keys mapped to dictionaries that
describe the properties of the named authentication method for the
organization - its enabled status and availability for use by the
organization.
Clients should use this to implement server-settings UI to change which
methods are enabled for the organization. For authentication UI itself,
clients should use the pre-authentication metadata returned by
[`GET /server_settings`](/api/get-server-settings).
**Changes**: In Zulip 9.0 (feature level 241), the values in this
dictionary were changed. Previously, the values were a simple boolean
indicating whether the backend is enabled or not.
realm_allow_message_editing:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organizations [message edit policy](/help/restrict-message-editing-and-deletion)
allows editing the content of messages.
realm_edit_topic_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can edit topics of any message.
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 5 = Everyone
- 6 = Nobody
**Changes**: Nobody added as an option in Zulip 7.0 (feature level 159).
New in Zulip 5.0 (feature level 75), replacing the previous
`allow_community_topic_editing` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_message_content_edit_limit_seconds:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be edited
with this organization's
[message edit policy](/help/restrict-message-editing-and-deletion).
Will not be 0. A `null` value means no limit: messages can be edited
regardless of how long ago they were sent.
**Changes**: No limit was represented using the
special value `0` before Zulip 6.0 (feature level 138).
realm_move_messages_within_stream_limit_seconds:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be moved within a
channel to another topic by users who have permission to do so based on this
organization's [topic edit policy](/help/restrict-moving-messages). This
setting does not affect moderators and administrators.
Will not be 0. A `null` value means no limit, so message topics can be
edited regardless of how long ago they were sent.
**Changes**: New in Zulip 7.0 (feature level 162). Previously, this time
limit was always 72 hours for users who were not administrators or
moderators.
realm_move_messages_between_streams_limit_seconds:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be moved between
channels by users who have permission to do so based on this organization's
[message move policy](/help/restrict-moving-messages). This setting does
not affect moderators and administrators.
Will not be 0. A `null` value means no limit, so messages can be moved
regardless of how long ago they were sent.
**Changes**: New in Zulip 7.0 (feature level 162). Previously, there was
no time limit for moving messages between channels for users with permission
to do so.
realm_enable_read_receipts:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether read receipts is enabled in the organization or not.
If disabled, read receipt data will be unavailable to clients, regardless
of individual users' personal read receipt settings. See also the
`send_read_receipts` setting within `realm_user_settings_defaults`.
**Changes**: New in Zulip 6.0 (feature level 137).
realm_icon_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's [profile icon](/help/create-your-organization-profile).
realm_icon_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's
[profile icon](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the organization's icon.
- "G" means generated by Gravatar (the default).
- "U" means uploaded by an organization administrator.
max_icon_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size allowed for the organization's
icon. Useful for UI allowing editing the organization's icon.
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `max_icon_file_size`.
realm_logo_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's wide logo configured in the
[organization profile](/help/create-your-organization-profile).
realm_logo_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
realm_night_logo_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's dark theme wide-format logo configured in the
[organization profile](/help/create-your-organization-profile).
realm_night_logo_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's dark theme
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
max_logo_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size allowed for the uploaded organization logos.
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `max_logo_file_size`.
realm_bot_domain:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The fake email domain that will be used for new bots created this
organization. Useful for UI for creating bots.
realm_uri:
type: string
deprecated: true
description: |
Present if `realm` is present in `fetch_event_types`.
The URL for the organization. Alias of `realm_url`.
**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
realm_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL for the organization.
**Changes**: New in Zulip 9.0 (feature level 257), replacing the
deprecated `realm_uri`.
realm_available_video_chat_providers:
type: object
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary where each entry describes a supported
[video call provider](/help/start-a-call)
that is configured on this server and could be selected by an
organization administrator.
Useful for administrative settings UI that allows changing the
realm setting `video_chat_provider`.
additionalProperties:
description: |
`{provider_name}`: Dictionary containing the details of the
video call provider with the name of the chat provider as
the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the video call provider.
id:
type: integer
description: |
The ID of the video call provider.
realm_presence_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether online presence of other users is shown in this
organization.
settings_send_digest_emails:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this Zulip server is configured to allow organizations to
enable [digest emails](/help/digest-emails).
Relevant for administrative settings UI that can change the digest
email settings.
realm_is_zephyr_mirror_realm:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization is a Zephyr mirror realm.
realm_email_auth_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has enabled Zulip's default email and password
authentication feature. Determines whether Zulip stores a password
for the user and clients should offer any UI for changing the user's
Zulip password.
realm_password_auth_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization allows any sort of password-based
authentication (whether via EmailAuthBackend or LDAP passwords).
Determines whether a client might ever need to display a password prompt
(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)
before presenting a login page).
realm_push_notifications_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether push notifications are enabled for this organization. Typically
`true` for Zulip Cloud and self-hosted realms that have a valid
registration for the [Mobile push notifications
service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html),
and `false` for self-hosted servers that do not.
**Changes**: Before Zulip 8.0 (feature level 231), this incorrectly was
`true` for servers that were partly configured to use the Mobile Push
Notifications Service but not properly registered.
realm_push_notifications_enabled_end_timestamp:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
If the server expects the realm's push notifications access to end at a
definite time in the future, the UNIX timestamp (UTC) at which this is
expected to happen. Mobile clients should use this field to display warnings
to users when the indicated timestamp is near.
**Changes**: New in Zulip 8.0 (feature level 231).
realm_upload_quota_mib:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
The total quota for uploaded files in this organization.
Clients are not responsible for checking this quota; it is included
in the API only for display purposes.
If `null`, there is no limit.
**Changes**: Before Zulip 9.0 (feature level 251), this field
was incorrectly measured in bytes, not MiB.
New in Zulip 5.0 (feature level 72). Previously,
this was called `realm_upload_quota`.
realm_org_type:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [organization type](/help/organization-type) for the realm.
Useful only to clients supporting changing this setting for the
organization, or clients implementing onboarding content or
other features that varies with organization type.
- 0 = Unspecified
- 10 = Business
- 20 = Open-source project
- 30 = Education (non-profit)
- 35 = Education (for-profit)
- 40 = Research
- 50 = Event or conference
- 60 = Non-profit (registered)
- 70 = Government
- 80 = Political group
- 90 = Community
- 100 = Personal
- 1000 = Other
**Changes**: New in Zulip 6.0 (feature level 128).
realm_plan_type:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The plan type of the organization.
- 1 = Self-hosted organization (SELF_HOSTED)
- 2 = Zulip Cloud free plan (LIMITED)
- 3 = Zulip Cloud Standard plan (STANDARD)
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
realm_enable_guest_user_indicator:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether clients should display "(guest)" after the names of
guest users to prominently highlight their status.
**Changes**: New in Zulip 8.0 (feature level 216).
realm_can_access_all_users_group:
type: integer
description: |
The ID of the [user group](/api/get-user-groups) whose members
are allowed to access all users in the organization.
This setting can currently only be set to `"role:members"`
and `"role:everyone"` system groups.
**Changes**: New in Zulip 8.0 (feature level 225).
zulip_plan_is_not_limited:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization is using a limited (Zulip Cloud Free) plan.
upgrade_text_for_wide_organization_logo:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
Text to use when displaying UI for wide organization logos, a feature
that is currently not available on the Zulip Cloud Free plan.
Useful only for clients supporting administrative UI for uploading
a new wide organization logo to brand the organization.
realm_default_external_accounts:
type: object
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary where each entry describes a default external
account type that can be configured with Zulip's [custom
profile fields feature](/help/custom-profile-fields).
**Changes**: New in Zulip 2.1.0.
additionalProperties:
description: |
`{site_name}`: Dictionary containing the details of the
default external account provider with the name of the
website as the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the external account provider
text:
type: string
description: |
The text describing the external account.
hint:
type: string
description: |
The help text to be displayed for the
custom profile field in user-facing
settings UI for configuring custom
profile fields for this account.
url_pattern:
type: string
description: |
The regex pattern of the URL of a profile page
on the external site.
jitsi_server_url:
type: string
deprecated: true
description: |
Present if `realm` is present in `fetch_event_types`.
The base URL to be used to create Jitsi video calls. Equals
`realm_jitsi_server_url || server_jitsi_server_url`.
**Changes**: Deprecated in Zulip 8.0 (feature level 212) and will
eventually be removed. Previously, the Jitsi server to use was not
configurable on a per-realm basis, and this field contained the server's
configured Jitsi server. (Which is now provided as
`server_jitsi_server_url`). Clients supporting older versions should fall
back to this field when creating calls: using `realm_jitsi_server_url ||
server_jitsi_server_url` with newer servers and using `jitsi_server_url`
with servers below feature level 212.
development_environment:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this Zulip server is a development environment. Used
to control certain features or UI (such as error popups)
that should only apply when connected to a Zulip development
environment.
server_generation:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
A timestamp indicating when the process hosting this
event queue was started. Clients will likely only find
this value useful for inclusion in detailed error reports.
password_min_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
This Zulip server's configured minimum required length for passwords.
Necessary for password change UI to show whether the password
will be accepted.
password_min_guesses:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
This Zulip server's configured minimum `zxcvbn` minimum guesses.
Necessary for password change UI to show whether the password
will be accepted.
giphy_rating_options:
type: object
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary where each entry describes a valid rating
that is configured on this server and could be selected by an
organization administrator.
Useful for administrative settings UI that allows changing the
allowed rating of GIFs.
additionalProperties:
description: |
`{rating_name}`: Dictionary containing the details of the
rating with the name of the rating as
the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The description of the rating option.
id:
type: integer
description: |
The ID of the rating option.
max_file_upload_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size that can be uploaded to this Zulip server.
max_avatar_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum avatar size that can be uploaded to this Zulip server.
server_inline_image_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is configured with support for inline image previews.
Clients containing administrative UI for changing
`realm_inline_image_preview` should consult this field before offering
that feature.
server_inline_url_embed_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is configured with support for inline URL previews.
Clients containing administrative UI for changing
`realm_inline_url_embed_preview` should consult this field before offering
that feature.
server_thumbnail_formats:
description: |
A list describing the image formats that uploaded
images will be thumbnailed into. Any image with a
source starting with `/user_uploads/thumbnail/` can
have its last path component replaced with any of the
names contained in this list, to obtain the desired
thumbnail size.
**Changes**: New in Zulip 9.0 (feature level 273).
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The file path component of the thumbnail format.
max_width:
type: integer
description: |
The maximum width of this format.
max_height:
type: integer
description: |
The maximum height of this format.
format:
type: string
description: |
The extension of this format.
animated:
type: boolean
description: |
If this file format is animated. These formats
are only generated for uploaded imates which
themselves are animated.
server_avatar_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server allows avatar changes. Similar to
`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`
Zulip server level setting.
server_name_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server allows name changes. Similar to
`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`
Zulip server level setting.
server_needs_upgrade:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is running an old version based on the Zulip
[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),
such that the web app will display to the current user a prominent warning.
**Changes**: New in Zulip 5.0 (feature level 74).
server_web_public_streams_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level
setting. A server that has disabled this setting intends to not offer [web
public channels](/help/public-access-option) to realms it hosts. (Zulip Cloud
defaults to `true`; self-hosted servers default to `false`).
Clients should use this to determine whether to offer UI for the
realm-level setting for enabling web-public channels
(`realm_enable_spectator_access`).
**Changes**: New in Zulip 5.0 (feature level 110).
server_emoji_data_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL to a JSON file that describes which emoji names map to which
emoji codes, for all Unicode emoji this Zulip server accepts.
The data at the given URL is a JSON object with one property, `code_to_names`.
The value of that property is a JSON object where each key is an
[emoji code](/api/add-reaction#parameter-emoji_code) for an available
Unicode emoji, and each value is the corresponding
[emoji names](/api/add-reaction#parameter-emoji_name) for this emoji,
with the canonical name for the emoji always appearing first.
The HTTP response at that URL will have appropriate HTTP caching headers, such
any HTTP implementation should get a cached version if emoji haven't changed
since the last request.
**Changes**: New in Zulip 6.0 (feature level 140).
server_jitsi_server_url:
type: string
nullable: true
description: |
The URL of the Jitsi server that the Zulip server is configured to use by
default; the organization-level setting `realm_jitsi_server_url` takes
precedence over this setting when both are set.
**Changes**: New in Zulip 8.0 (feature level 212). Previously, this value
was available as the now-deprecated `jitsi_server_url`.
event_queue_longpoll_timeout_seconds:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Recommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.
This is guaranteed to be somewhat greater than the heartbeat frequency. It is important
that clients respect this parameter, so that increases in the heartbeat frequency do not
break clients.
**Changes**: New in Zulip 5.0 (feature level 74). Previously,
this was hardcoded to 90 seconds, and clients should use that as a fallback
value when interacting with servers where this field is not present.
realm_new_stream_announcements_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the channel to which automated messages announcing the
[creation of new channels][new-channel-announce] are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
[new-channel-announce]: /help/configure-automated-notices#new-channel-announcements
**Changes**: In Zulip 9.0 (feature level 241), renamed 'realm_notifications_stream_id'
to `realm_new_stream_announcements_stream_id`.
realm_signup_announcements_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the channel to which automated messages announcing
that [new users have joined the organization][new-user-announce] are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
[new-user-announce]: /help/configure-automated-notices#new-user-announcements
**Changes**: In Zulip 9.0 (feature level 241), renamed
'realm_signup_notifications_stream_id' to `realm_signup_announcements_stream_id`.
realm_zulip_update_announcements_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the channel to which automated messages announcing
new features or other end-user updates about the Zulip software are sent.
Will be `-1` if such automated messages are disabled.
Since these automated messages are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
**Changes**: New in Zulip 9.0 (feature level 242).
realm_user_settings_defaults:
type: object
additionalProperties: false
description: |
Present if `realm_user_settings_defaults` is present in `fetch_event_types`.
A dictionary containing the default values of settings for new users.
**Changes**: New in Zulip 5.0 (feature level 95).
properties:
twenty_four_hour_time:
type: boolean
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
**Changes**: New in Zulip 5.0 (feature level 99).
This value was previously available as
`realm_default_twenty_four_hour_time` in
the top-level response object (only when `realm` was
present in `fetch_event_types`).
dense_mode:
type: boolean
description: |
This setting has no effect at present. It is reserved for use in
controlling the default font size in Zulip.
web_mark_read_on_scroll_policy:
type: integer
description: |
Whether or not to mark messages as read when the user scrolls through their
feed.
- 1 - Always
- 2 - Only in conversation views
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
way for the user to configure this behavior on the web, and the Zulip web and
desktop apps behaved like the "Always" setting when marking messages as read.
web_channel_default_view:
type: integer
description: |
Web/desktop app setting controlling the default navigation
behavior when clicking on a channel link.
- 1 - Top topic in the channel
- 2 - Channel feed
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
was not configurable, and every user had the "Channel feed" behavior.
starred_message_counts:
type: boolean
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
receives_typing_notifications:
type: boolean
description: |
Whether the user is configured to receive typing notifications from
other users. The server will only deliver typing notifications events
to users who for whom this is enabled.
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
only options to disable sending typing notifications.
fluid_layout_width:
type: boolean
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent conversations) on wide screens.
high_contrast_mode:
type: boolean
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
web_font_size_px:
description: |
User-configured primary `font-size` for the web application, in pixels.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
only adjustable via browser zoom. Note that this setting was not fully
implemented at this feature level.
type: integer
example: 14
web_line_height_percent:
description: |
User-configured primary `line-height` for the web application, in percent, so a
value of 120 represents a `line-height` of 1.2.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
not user-configurable. Note that this setting was not fully implemented at this
feature level.
type: integer
example: 122
color_scheme:
type: integer
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
translate_emoticons:
type: boolean
description: |
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
in messages the user sends.
display_emoji_reaction_users:
type: boolean
description: |
Whether to display the names of reacting users on a message.
When enabled, clients should display the names of reacting
users, rather than a count, for messages with few total
reactions. The ideal cutoff may depend on the space
available for displaying reactions; the official web
application displays names when 3 or fewer total reactions
are present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
default_language:
type: string
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
web_home_view:
type: string
description: |
The [home view](/help/configure-home-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent conversations view
- "inbox" - Inbox view
- "all_messages" - Combined feed view
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
called `default_view`, which was new in Zulip 4.0 (feature level 42).
web_escape_navigates_to_home_view:
type: boolean
description: |
Whether the escape key navigates to the
[configured home view](/help/configure-home-view).
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
was called `escape_navigates_to_default_view`, which was new in Zulip
5.0 (feature level 107).
left_side_userlist:
type: boolean
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
emojiset:
type: string
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
demote_inactive_streams:
type: integer
description: |
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
user_list_style:
type: integer
description: |
The style selected by the user for the right sidebar user list.
- 1 - Compact
- 2 - With status
- 3 - With avatar and status
**Changes**: New in Zulip 6.0 (feature level 141).
web_animate_image_previews:
type: string
description: |
Controls how animated images should be played in the message feed in the web/desktop application.
- "always" - Always play the animated images in the message feed.
- "on_hover" - Play the animated images on hover over them in the message feed.
- "never" - Never play animated images in the message feed.
**Changes**: New in Zulip 9.0 (feature level 275).
web_stream_unreads_count_display_policy:
type: integer
description: |
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
Channels that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All channels
- 2 - Unmuted channels and topics
- 3 - No channels
**Changes**: New in Zulip 8.0 (feature level 210).
enable_stream_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for channel messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for channel messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for channel messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for channel messages.
notification_sound:
type: string
description: |
Notification sound name.
enable_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for direct messages and @-mentions.
enable_sounds:
type: boolean
description: |
Enable audible desktop notifications for direct messages and
@-mentions.
enable_offline_email_notifications:
type: boolean
description: |
Enable email notifications for direct messages and @-mentions received
when the user is offline.
enable_offline_push_notifications:
type: boolean
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is offline.
enable_online_push_notifications:
type: boolean
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is online.
enable_followed_topic_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_email_notifications:
type: boolean
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_push_notifications:
type: boolean
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_followed_topic_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
enable_digest_emails:
type: boolean
description: |
Enable digest emails when the user is away.
enable_marketing_emails:
type: boolean
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
enable_login_emails:
type: boolean
description: |
Enable email notifications for new logins to account.
message_content_in_email_notifications:
type: boolean
description: |
Include the message's content in email notifications for new messages.
pm_content_in_desktop_notifications:
type: boolean
description: |
Include content of direct messages in desktop notifications.
wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
enable_followed_topic_wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
should send notifications like a personal mention.
**Changes**: New in Zulip 8.0 (feature level 189).
desktop_icon_count_display:
type: integer
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unread messages
- 2 - DMs, mentions, and followed topics
- 3 - DMs and mentions
- 4 - None
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions,
and followed topics` option, renumbering the options to insert it in
order.
realm_name_in_email_notifications_policy:
type: integer
description: |
Whether to [include organization name in subject of message notification
emails](/help/email-notifications#include-organization-name-in-subject-line).
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
previous `realm_name_in_notifications` boolean;
`true` corresponded to `Always`, and `false` to `Never`.
automatically_follow_topics_policy:
type: integer
description: |
Which [topics to follow automatically](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
automatically_unmute_topics_in_muted_streams_policy:
type: integer
description: |
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
automatically_follow_topics_where_mentioned:
type: boolean
description: |
Whether the server will automatically mark the user as following
topics where the user is mentioned.
**Changes**: New in Zulip 8.0 (feature level 235).
presence_enabled:
type: boolean
description: |
Display the presence status to other users when online.
enter_sends:
type: boolean
description: |
Whether the user setting for [sending on pressing Enter](/help/mastering-the-compose-box#toggle-between-ctrl-enter-and-enter-to-send-a-message)
in the compose box is enabled.
enable_drafts_synchronization:
type: boolean
description: |
A boolean parameter to control whether synchronizing drafts is enabled for
the user. When synchronization is disabled, all drafts stored in the server
will be automatically deleted from the server.
This does not do anything (like sending events) to delete local copies of
drafts stored in clients.
email_notifications_batching_period_seconds:
type: integer
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
available_notification_sounds:
type: array
items:
type: string
description: |
Array containing the names of the notification sound options
supported by this Zulip server. Only relevant to support UI
for configuring notification sounds.
emojiset_choices:
description: |
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
send_private_typing_notifications:
type: boolean
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
direct messages.
**Changes**: New in Zulip 5.0 (feature level 105).
send_stream_typing_notifications:
type: boolean
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
channel messages.
**Changes**: New in Zulip 5.0 (feature level 105).
send_read_receipts:
type: boolean
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
email_address_visibility:
$ref: "#/components/schemas/EmailAddressVisibility"
web_navigate_to_sent_message:
type: boolean
description: |
Web/desktop app setting for whether the user's view should
automatically go to the conversation where they sent a message.
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
this behavior was not configurable.
realm_users:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
A array of dictionaries where each entry describes a user
whose account has not been deactivated. Note that unlike
the usual User dictionary, this does not contain the `is_active`
key, as all the users present in this array have active accounts.
If the current user is a guest whose access to users is limited by a
`can_access_all_users_group` policy, and the event queue was registered
with the `user_list_incomplete` client capability, then users that the
current user cannot access will not be included in this array. If the
current user's access to a user is restricted but the client lacks this
capability, then that inaccessible user will appear in the users array as
an "Unknown user" object with the usual format but placeholder data whose
only variable content is the user ID.
See also `cross_realm_bots` and `realm_non_active_users`.
**Changes**: Before Zulip 8.0 (feature level 232), the
`user_list_incomplete` client capability did not exist, and so all
clients whose access to a new user was prevented by
`can_access_all_users_group` policy would receive a fake "Unknown
user" event for such users.
items:
$ref: "#/components/schemas/User"
realm_non_active_users:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
A array of dictionaries where each entry describes a user
whose account has been deactivated. Note that unlike
the usual User dictionary this does not contain the `is_active`
key as all the users present in this array have deactivated
accounts.
items:
$ref: "#/components/schemas/User"
avatar_source:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The avatar data source type for the current user.
Value values are `G` (gravatar) and `U` (uploaded by user).
avatar_url_medium:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The avatar URL for the current user at 500x500 resolution, appropriate
for use in settings UI showing the user's avatar.
avatar_url:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The URL of the avatar for the current user at 100x100
resolution. See also `avatar_url_medium`.
can_create_streams:
type: boolean
deprecated: true
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create at least one type
of channel with the organization's [channel creation
policy](/help/configure-who-can-create-channels). Its value will
always equal `can_create_public_streams || can_create_private_streams`.
**Changes**: Deprecated in Zulip 5.0 (feature level 102), when
the new `create_private_stream_policy` and
`create_public_stream_policy` properties introduced the
possibility that a user could only create one type of channel.
This field will be removed in a future release.
can_create_public_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create public channels with
the organization's [channel creation policy](/help/configure-who-can-create-channels).
**Changes**: New in Zulip 5.0 (feature level 102). In older
versions, the deprecated `can_create_streams` property should be
used to determine whether the user can create public channels.
can_create_private_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create private channels with
the organization's [channel creation policy](/help/configure-who-can-create-channels).
**Changes**: New in Zulip 5.0 (feature level 102). In older
versions, the deprecated `can_create_streams` property should be
used to determine whether the user can create private channels.
can_create_web_public_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create public channels with
the organization's [channel creation policy](/help/configure-who-can-create-channels).
Note that this will be false if the Zulip server does not have the
`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has
not enabled the `enable_spectator_access` realm setting.
**Changes**: New in Zulip 5.0 (feature level 103).
can_subscribe_other_users:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to subscribe other users to channels with
the organization's [channels policy](/help/configure-who-can-invite-to-channels).
can_invite_others_to_realm:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user [is allowed to invite others][who-can-send-invitations]
to the organization.
**Changes**: New in Zulip 4.0 (feature level 51).
[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations
is_admin:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization administrator](/api/roles-and-permissions).
is_owner:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization owner](/api/roles-and-permissions).
**Changes**: New in Zulip 3.0 (feature level 11).
is_billing_admin:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
is_moderator:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization moderator](/api/roles-and-permissions).
**Changes**: New in Zulip 4.0 (feature level 60).
is_guest:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is a [guest user](/api/roles-and-permissions).
user_id:
type: integer
description: |
Present if `realm_user` is present in `fetch_event_types`.
The unique ID for the current user.
email:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The Zulip API email address for the current user. See also
`delivery_email`; these may be the same or different depending
on the user's `email_address_visibility` policy.
delivery_email:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The user's email address, appropriate for UI for changing
the user's email address. See also `email`.
full_name:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The full name of the current user.
cross_realm_bots:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
Array of dictionaries where each dictionary contains details of
a single cross realm bot. Cross-realm bots are special system bot accounts
like Notification Bot.
Most clients will want to combine this with `realm_users` in many
contexts.
items:
allOf:
- $ref: "#/components/schemas/UserBase"
- additionalProperties: false
properties:
user_id: {}
delivery_email: {}
email: {}
full_name: {}
date_joined: {}
is_active: {}
is_owner: {}
is_admin: {}
is_guest: {}
is_billing_admin: {}
is_bot: {}
# Referenced schema properties are rendered before any
# non-referenced properties in the API documentation, so
# `is_system_bot` appears last instead of in this order.
# General practice should be to define properties in the
# same order that they are rendered in the API documentation.
# TODO: See if we can match the order of properties as
# listed here when rendered in the API documentation.
is_system_bot:
type: boolean
description: |
Whether the user is a system bot. System bots are special
bot user accounts that are managed by the system, rather than
the organization's administrators.
**Changes**: This field was called `is_cross_realm_bot`
before Zulip 5.0 (feature level 83).
bot_type:
nullable: true
bot_owner_id:
nullable: true
role: {}
timezone: {}
avatar_url:
nullable: true
avatar_version: {}
profile_data: {}
server_supported_permission_settings:
description: |
Present if `realm` is present in `fetch_event_types`.
Configuration for various group permission settings.
We consider this part of the Zulip API to be unstable
and may change significantly in future versions.
**Changes**: New in Zulip 8.0 (feature level 221).
type: object
additionalProperties: false
properties:
realm:
type: object
description: |
Configuration for realm level group permission settings.
additionalProperties:
$ref: "#/components/schemas/GroupPermissionSetting"
stream:
type: object
description: |
Configuration for channel level group permission settings.
additionalProperties:
$ref: "#/components/schemas/GroupPermissionSetting"
group:
type: object
description: |
Configuration for group level group permission settings.
additionalProperties:
$ref: "#/components/schemas/GroupPermissionSetting"
example:
{
"last_event_id": -1,
"msg": "",
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
"realm_emoji":
{
"1":
{
"author_id": 5,
"deactivated": false,
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
},
"2":
{
"author_id": 3,
"deactivated": false,
"id": "2",
"name": "animated_img",
"source_url": "/user_avatars/1/emoji/images/animated_img.gif",
"still_url": "/user_avatars/1/emoji/images/still/animated_img.png",
},
},
"result": "success",
"zulip_feature_level": 2,
"zulip_version": "5.0-dev-1650-gc3fd37755f",
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
}
/server_settings:
get:
operationId: get-server-settings
summary: Get server settings
tags: ["server_and_organizations"]
x-response-description: |
Please note that not all of these attributes are guaranteed to appear in a
response, for two reasons:
* This endpoint has evolved over time, so responses from older Zulip servers
might be missing some keys (in which case a client should assume the
appropriate default).
* If a `/server_settings` request is made to the root domain of a
multi-subdomain server, like the root domain of zulip.com, the settings
that are realm-specific are not known and thus not provided.
description: |
Fetch global settings for a Zulip server.
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
- If this is a Zulip server, and if so, what version of Zulip it's running.
- What a Zulip client (e.g. a mobile app or
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
know in order to display a login prompt for the server (e.g. what
authentication methods are available).
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
authentication_methods:
type: object
additionalProperties: false
deprecated: true
description: |
Each key-value pair in the object indicates whether the authentication
method is enabled on this server.
**Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive
`external_authentication_methods`.
properties:
password:
description: |
Whether the user can authenticate using password.
type: boolean
dev:
description: |
Whether the user can authenticate using development API key.
type: boolean
email:
description: |
Whether the user can authenticate using email.
type: boolean
ldap:
description: |
Whether the user can authenticate using LDAP.
type: boolean
remoteuser:
description: |
Whether the user can authenticate using REMOTE_USER.
type: boolean
github:
description: |
Whether the user can authenticate using their GitHub account.
type: boolean
azuread:
description: |
Whether the user can authenticate using their Azure Active Directory account.
type: boolean
gitlab:
description: |
Whether the user can authenticate using their GitLab account.
**Changes**: New in Zulip 3.0 (feature level 1).
type: boolean
apple:
description: |
Whether the user can authenticate using their Apple account.
type: boolean
google:
description: |
Whether the user can authenticate using their Google account.
type: boolean
saml:
description: |
Whether the user can authenticate using SAML.
type: boolean
openid connect:
description: |
Whether the user can authenticate using OpenID Connect.
type: boolean
external_authentication_methods:
type: array
description: |
A list of dictionaries describing the available external
authentication methods (E.g. Google, GitHub, or SAML)
enabled for this organization.
The list is sorted in the order in which these
authentication methods should be displayed.
**Changes**: New in Zulip 2.1.0.
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: |
A unique, table, machine-readable name for the authentication method,
intended to be used by clients with special behavior for specific
authentication methods to correctly identify the method.
display_name:
type: string
description: |
Display name of the authentication method, to be used in all buttons
for the authentication method.
display_icon:
type: string
nullable: true
description: |
URL for an image to be displayed as an icon in all buttons for
the external authentication method.
When `null`, no icon should be displayed.
login_url:
type: string
description: |
URL to be used to initiate authentication using this method.
signup_url:
type: string
description: |
URL to be used to initiate account registration using this method.
zulip_feature_level:
type: integer
description: |
An integer indicating what features are
available on the server. The feature level increases monotonically;
a value of N means the server supports all API features introduced
before feature level N. This is designed to provide a simple way
for client apps to decide whether the server supports a given
feature or API change. See the [changelog](/api/changelog) for
details on what each feature level means.
**Changes**: New in Zulip 3.0 (feature level 1). We recommend using an
implied value of 0 for Zulip servers that do not send this field.
zulip_version:
type: string
description: |
The server's version number. This is often a release version number,
like `2.1.7`. But for a server running a [version from Git][git-release],
it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`.
[git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions
zulip_merge_base:
type: string
description: |
The `git merge-base` between `zulip_version` and official branches
in the public
[Zulip server and web app repository](https://github.com/zulip/zulip),
in the same format as `zulip_version`. This will equal
`zulip_version` if the server is not running a fork of the Zulip server.
This will be `""` if unavailable.
**Changes**: New in Zulip 5.0 (feature level 88).
push_notifications_enabled:
type: boolean
description: |
Whether mobile/push notifications are configured.
is_incompatible:
type: boolean
description: |
Whether the Zulip client that has sent a request to this endpoint is
deemed incompatible with the server.
email_auth_enabled:
type: boolean
description: |
Setting for allowing users authenticate with an email-password
combination.
require_email_format_usernames:
type: boolean
description: |
Whether all valid usernames for authentication to this
organization will be email addresses. This is important
for clients to know whether to do client side validation
of email address format in a login prompt.
This value will be false if the server has [LDAP
authentication][ldap-auth] enabled with a username and
password combination.
[ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory
realm_uri:
type: string
deprecated: true
description: |
The organization's canonical URL. Alias of `realm_url`.
**Changes**: Deprecated in Zulip 9.0 (feature level 257). The term
"URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals).
realm_url:
type: string
description: |
The organization's canonical URL.
**Changes**: New in Zulip 9.0 (feature level 257), replacing the
deprecated `realm_uri`.
realm_name:
type: string
description: |
The organization's name (for display purposes).
realm_icon:
type: string
description: |
The URL for the organization's logo formatted as a square image,
used for identifying the organization in small locations in the
mobile and desktop apps.
realm_description:
type: string
description: |
HTML description of the organization, as configured by the [organization
profile](/help/create-your-organization-profile).
realm_web_public_access_enabled:
type: boolean
description: |
Whether the organization has enabled the creation of
[web-public channels](/help/public-access-option) and
at least one web-public channel on the server currently
exists. Clients that support viewing content
in web-public channels without an account can
use this to determine whether to offer that
feature on the login page for an organization.
**Changes**: New in Zulip 5.0 (feature level 116).
example:
{
"authentication_methods":
{
"password": true,
"dev": true,
"email": true,
"ldap": false,
"remoteuser": false,
"github": true,
"azuread": false,
"google": true,
"saml": true,
},
"zulip_version": "5.0-dev-1650-gc3fd37755f",
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
"push_notifications_enabled": false,
"msg": "",
"is_incompatible": false,
"email_auth_enabled": true,
"require_email_format_usernames": true,
"realm_uri": "http://localhost:9991",
"realm_url": "http://localhost:9991",
"realm_name": "Zulip Dev",
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
"realm_web_public_access_enabled": false,
"result": "success",
"external_authentication_methods":
[
{
"name": "saml:idp_name",
"display_name": "SAML",
"display_icon": null,
"login_url": "/accounts/login/social/saml/idp_name",
"signup_url": "/accounts/register/social/saml/idp_name",
},
{
"name": "google",
"display_name": "Google",
"display_icon": "/static/images/authentication_backends/googl_e-icon.png",
"login_url": "/accounts/login/social/google",
"signup_url": "/accounts/register/social/google",
},
{
"name": "github",
"display_name": "GitHub",
"display_icon": "/static/images/authentication_backends/github-icon.png",
"login_url": "/accounts/login/social/github",
"signup_url": "/accounts/register/social/github",
},
],
}
/settings:
patch:
operationId: update-settings
summary: Update settings
tags: ["users"]
description: |
This endpoint is used to edit the current user's settings.
**Changes**: Prior to Zulip 5.0 (feature level 80), this
endpoint only supported the `full_name`, `email`,
`old_password`, and `new_password` parameters. Notification
settings were managed by `PATCH /settings/notifications`, and
all other settings by `PATCH /settings/display`.
The feature level 80 migration to merge these endpoints did not
change how request parameters are encoded. However, it did change
the handling of any invalid parameters present in a request
(see feature level 78 change below).
As of feature level 80, the `PATCH /settings/display` and
`PATCH /settings/notifications` endpoints are deprecated aliases
for this endpoint for backwards-compatibility, and will be removed
once clients have migrated to use this endpoint.
Prior to Zulip 5.0 (feature level 78), this endpoint indicated
which parameters it had processed by including in the response
object `"key": value` entries for values successfully changed by
the request. That was replaced by the more ergonomic
[`ignored_parameters_unsupported`][ignored-parameters] array.
The `PATCH /settings/notifications` and `PATCH /settings/display`
endpoints also had this behavior of indicating processed parameters
before they became aliases of this endpoint in Zulip 5.0 (see
feature level 80 change above).
Before feature level 78, request parameters that were not supported
(or were unchanged) were silently ignored.
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- left_side_userlist
- emojiset
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
full_name:
description: |
A new display name for the user.
type: string
example: NewName
email:
description: |
Asks the server to initiate a confirmation sequence to change the user's email
address to the indicated value. The user will need to demonstrate control of the
new email address by clicking a confirmation link sent to that address.
type: string
example: newname@example.com
old_password:
description: |
The user's old Zulip password (or LDAP password, if LDAP authentication is in use).
Required only when sending the `new_password` parameter.
type: string
example: old12345
new_password:
description: |
The user's new Zulip password (or LDAP password, if LDAP authentication is in use).
The `old_password` parameter must be included in the request.
type: string
example: new12345
twenty_four_hour_time:
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
dense_mode:
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
web_mark_read_on_scroll_policy:
description: |
Whether or not to mark messages as read when the user scrolls through their
feed.
- 1 - Always
- 2 - Only in conversation views
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no
way for the user to configure this behavior on the web, and the Zulip web and
desktop apps behaved like the "Always" setting when marking messages as read.
type: integer
enum:
- 1
- 2
- 3
example: 1
web_channel_default_view:
description: |
Web/desktop app setting controlling the default navigation
behavior when clicking on a channel link.
- 1 - Top topic in the channel
- 2 - Channel feed
**Changes**: New in Zulip 9.0 (feature level 269). Previously, this
was not configurable, and every user had the "Channel feed" behavior.
type: integer
enum:
- 1
- 2
example: 1
starred_message_counts:
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
receives_typing_notifications:
description: |
Whether the user is configured to receive typing notifications from other users.
The server will only deliver typing notifications events to users who for whom this
is enabled.
By default, this is set to true, enabling user to receive typing
notifications from other users.
**Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only
options to disable sending typing notifications.
type: boolean
example: true
fluid_layout_width:
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent conversations) on wide screens.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
high_contrast_mode:
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
web_font_size_px:
description: |
User-configured primary `font-size` for the web application, in pixels.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was
only adjustable via browser zoom. Note that this setting was not fully
implemented at this feature level.
type: integer
example: 14
web_line_height_percent:
description: |
User-configured primary `line-height` for the web application, in percent, so a
value of 120 represents a `line-height` of 1.2.
**Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was
not user-configurable. Note that this setting was not fully implemented at this
feature level.
type: integer
example: 122
color_scheme:
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: integer
enum:
- 1
- 2
- 3
example: 1
enable_drafts_synchronization:
description: |
A boolean parameter to control whether synchronizing drafts is enabled for
the user. When synchronization is disabled, all drafts stored in the server
will be automatically deleted from the server.
This does not do anything (like sending events) to delete local copies of
drafts stored in clients.
**Changes**: New in Zulip 5.0 (feature level 87).
type: boolean
example: true
translate_emoticons:
description: |
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
in messages the user sends.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
display_emoji_reaction_users:
description: |
Whether to display the names of reacting users on a message.
When enabled, clients should display the names of reacting users, rather than
a count, for messages with few total reactions. The ideal cutoff may depend on
the space available for displaying reactions; the official web application
displays names when 3 or fewer total reactions are present with this setting
enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
type: boolean
example: false
default_language:
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
type: string
example: en
web_home_view:
description: |
The [home view](/help/configure-home-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent conversations view
- "inbox" - Inbox view
- "all_messages" - Combined feed view
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this was
called `default_view`, which was new in Zulip 4.0 (feature level 42).
Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
type: string
example: all_messages
web_escape_navigates_to_home_view:
description: |
Whether the escape key navigates to the
[configured home view](/help/configure-home-view).
**Changes**: New in Zulip 8.0 (feature level 219). Previously, this
was called `escape_navigates_to_default_view`, which was new in Zulip
5.0 (feature level 107).
type: boolean
example: true
left_side_userlist:
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: boolean
example: true
emojiset:
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
type: string
example: "google"
demote_inactive_streams:
description: |
Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
type: integer
enum:
- 1
- 2
- 3
example: 1
user_list_style:
description: |
The style selected by the user for the right sidebar user list.
- 1 - Compact
- 2 - With status
- 3 - With avatar and status
**Changes**: New in Zulip 6.0 (feature level 141).
type: integer
enum:
- 1
- 2
- 3
example: 1
web_animate_image_previews:
description: |
Controls how animated images should be played in the message feed in the web/desktop application.
- "always" - Always play the animated images in the message feed.
- "on_hover" - Play the animated images on hover over them in the message feed.
- "never" - Never play animated images in the message feed.
**Changes**: New in Zulip 9.0 (feature level 275).
type: string
enum:
- always
- on_hover
- never
example: on_hover
web_stream_unreads_count_display_policy:
description: |
Configuration for which channels should be displayed with a numeric unread count in the left sidebar.
Channels that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All channels
- 2 - Unmuted channels and topics
- 3 - No channels
**Changes**: New in Zulip 8.0 (feature level 210).
type: integer
enum:
- 1
- 2
- 3
example: 2
timezone:
description: |
The IANA identifier of the user's [configured time zone](/help/change-your-timezone).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
type: string
example: "Asia/Kolkata"
enable_stream_desktop_notifications:
description: |
Enable visual desktop notifications for channel messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_stream_email_notifications:
description: |
Enable email notifications for channel messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_stream_push_notifications:
description: |
Enable mobile notifications for channel messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_stream_audible_notifications:
description: |
Enable audible desktop notifications for channel messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
notification_sound:
description: |
Notification sound name.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
type: string
example: ding
enable_desktop_notifications:
description: |
Enable visual desktop notifications for direct messages and @-mentions.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_sounds:
description: |
Enable audible desktop notifications for direct messages and
@-mentions.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
email_notifications_batching_period_seconds:
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
**Changes**: New in Zulip 5.0 (feature level 82)
type: integer
example: 120
enable_offline_email_notifications:
description: |
Enable email notifications for direct messages and @-mentions received
when the user is offline.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_offline_push_notifications:
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is offline.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_online_push_notifications:
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is online.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_followed_topic_desktop_notifications:
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
enable_followed_topic_email_notifications:
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
enable_followed_topic_push_notifications:
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: false
enable_followed_topic_audible_notifications:
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: false
enable_digest_emails:
description: |
Enable digest emails when the user is away.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_marketing_emails:
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_login_emails:
description: |
Enable email notifications for new logins to account.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
message_content_in_email_notifications:
description: |
Include the message's content in email notifications for new messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
pm_content_in_desktop_notifications:
description: |
Include content of direct messages in desktop notifications.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
wildcard_mentions_notify:
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enable_followed_topic_wildcard_mentions_notify:
description: |
Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics
should send notifications like a personal mention.
**Changes**: New in Zulip 8.0 (feature level 189).
type: boolean
example: true
desktop_icon_count_display:
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unread messages
- 2 - DMs, mentions, and followed topics
- 3 - DMs and mentions
- 4 - None
**Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed
topics` option, renumbering the options to insert it in order.
Before Zulip 5.0 (feature level 80), this setting was managed by the
`PATCH /settings/notifications` endpoint.
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
realm_name_in_email_notifications_policy:
description: |
Whether to [include organization name in subject of message notification
emails](/help/email-notifications#include-organization-name-in-subject-line).
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: New in Zulip 7.0 (feature level 168), replacing the
previous `realm_name_in_notifications` boolean;
`true` corresponded to `Always`, and `false` to `Never`.
Before Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications`
setting was managed by the `PATCH /settings/notifications` endpoint.
type: integer
enum:
- 1
- 2
- 3
example: 1
automatically_follow_topics_policy:
description: |
Which [topics to follow automatically](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
automatically_unmute_topics_in_muted_streams_policy:
description: |
Which [topics to unmute automatically in muted channels](/help/mute-a-topic).
- 1 - Topics the user participates in
- 2 - Topics the user sends a message to
- 3 - Topics the user starts
- 4 - Never
**Changes**: New in Zulip 8.0 (feature level 214).
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
automatically_follow_topics_where_mentioned:
description: |
Whether the server will automatically mark the user as following
topics where the user is mentioned.
**Changes**: New in Zulip 8.0 (feature level 235).
type: boolean
example: true
presence_enabled:
description: |
Display the presence status to other users when online.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
type: boolean
example: true
enter_sends:
description: |
Whether pressing Enter in the compose box sends a message
(or saves a message edit).
**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by
the `POST /users/me/enter-sends` endpoint, with the same parameter format.
type: boolean
example: true
send_private_typing_notifications:
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
direct messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
send_stream_typing_notifications:
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
channel messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
send_read_receipts:
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
type: boolean
example: true
email_address_visibility:
description: |
The [policy][permission-level] this user has selected for [which other
users][help-email-visibility] in this organization can see their real
email address.
- 1 = Everyone
- 2 = Members only
- 3 = Administrators only
- 4 = Nobody
- 5 = Moderators only
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
realm-level setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[help-email-visibility]: /help/configure-email-visibility
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
example: 1
web_navigate_to_sent_message:
description: |
Web/desktop app setting for whether the user's view should
automatically go to the conversation where they sent a message.
**Changes**: New in Zulip 9.0 (feature level 268). Previously,
this behavior was not configurable.
type: boolean
example: true
encoding:
twenty_four_hour_time:
contentType: application/json
dense_mode:
contentType: application/json
web_mark_read_on_scroll_policy:
contentType: application/json
web_channel_default_view:
contentType: application/json
starred_message_counts:
contentType: application/json
receives_typing_notifications:
contentType: application/json
fluid_layout_width:
contentType: application/json
high_contrast_mode:
contentType: application/json
web_font_size_px:
contentType: application/json
web_line_height_percent:
contentType: application/json
color_scheme:
contentType: application/json
enable_drafts_synchronization:
contentType: application/json
translate_emoticons:
contentType: application/json
display_emoji_reaction_users:
contentType: application/json
web_escape_navigates_to_home_view:
contentType: application/json
left_side_userlist:
contentType: application/json
demote_inactive_streams:
contentType: application/json
user_list_style:
contentType: application/json
web_stream_unreads_count_display_policy:
contentType: application/json
enable_stream_desktop_notifications:
contentType: application/json
enable_stream_email_notifications:
contentType: application/json
enable_stream_push_notifications:
contentType: application/json
enable_stream_audible_notifications:
contentType: application/json
enable_desktop_notifications:
contentType: application/json
enable_sounds:
contentType: application/json
email_notifications_batching_period_seconds:
contentType: application/json
enable_offline_email_notifications:
contentType: application/json
enable_offline_push_notifications:
contentType: application/json
enable_online_push_notifications:
contentType: application/json
enable_followed_topic_desktop_notifications:
contentType: application/json
enable_followed_topic_email_notifications:
contentType: application/json
enable_followed_topic_push_notifications:
contentType: application/json
enable_followed_topic_audible_notifications:
contentType: application/json
enable_digest_emails:
contentType: application/json
enable_marketing_emails:
contentType: application/json
enable_login_emails:
contentType: application/json
message_content_in_email_notifications:
contentType: application/json
pm_content_in_desktop_notifications:
contentType: application/json
wildcard_mentions_notify:
contentType: application/json
enable_followed_topic_wildcard_mentions_notify:
contentType: application/json
desktop_icon_count_display:
contentType: application/json
realm_name_in_email_notifications_policy:
contentType: application/json
automatically_follow_topics_policy:
contentType: application/json
automatically_unmute_topics_in_muted_streams_policy:
contentType: application/json
automatically_follow_topics_where_mentioned:
contentType: application/json
presence_enabled:
contentType: application/json
enter_sends:
contentType: application/json
send_private_typing_notifications:
contentType: application/json
send_stream_typing_notifications:
contentType: application/json
send_read_receipts:
contentType: application/json
email_address_visibility:
contentType: application/json
web_navigate_to_sent_message:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SuccessIgnoredParameters"
/streams/{stream_id}/members:
get:
operationId: get-subscribers
summary: Get channel subscribers
tags: ["channels"]
description: |
Get all users subscribed to a channel.
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
subscribers:
type: array
items:
type: integer
description: |
A list containing the IDs of all active users who are subscribed
to the channel.
example:
{"result": "success", "msg": "", "subscribers": [11, 26]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidChannelError"
- description: |
An example JSON response for when the requested channel does not exist,
or where the user does not have permission to access the target channel:
/streams:
get:
operationId: get-streams
summary: Get all channels
tags: ["channels"]
description: |
Get all channels that the user [has access to](/help/channel-permissions).
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: include
parameters:
enum:
- include_public
description: |
You may pass in one or more of the parameters mentioned below
as URL query parameters, like so:
parameters:
- name: include_public
in: query
description: |
Include all public channels.
schema:
type: boolean
default: true
example: false
- name: include_web_public
in: query
description: |
Include all web-public channels.
schema:
type: boolean
default: false
example: true
- name: include_subscribed
in: query
description: |
Include all channels that the user is subscribed to.
schema:
type: boolean
default: true
example: false
- name: include_all_active
in: query
description: |
Include all active channels. The user must have administrative privileges
to use this parameter.
schema:
type: boolean
default: false
example: true
- name: include_default
in: query
description: |
Include all default channels for the user's realm.
schema:
type: boolean
default: false
example: true
- name: include_owner_subscribed
in: query
description: |
If the user is a bot, include all channels that the bot's owner is
subscribed to.
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: {}
streams:
description: |
A list of channel objects with details on the requested channels.
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicChannelBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
creator_id:
nullable: true
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
can_remove_subscribers_group: {}
stream_weekly_traffic:
type: integer
nullable: true
description: |
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.
is_default:
type: boolean
description: |
Only present when [`include_default`][include_default]
parameter is `true`.
Whether the given channel is a
[default channel](/help/set-default-channels-for-new-users).
[include_default]: /api/get-streams#parameter-include_default
required:
- stream_id
- name
- description
- date_created
- creator_id
- invite_only
- rendered_description
- is_web_public
- stream_post_policy
- message_retention_days
- history_public_to_subscribers
- first_message_id
- is_announcement_only
- can_remove_subscribers_group
- stream_weekly_traffic
example:
{
"msg": "",
"result": "success",
"streams":
[
{
"can_remove_subscribers_group": 10,
"creator_id": null,
"date_created": 1691057093,
"description": "A private channel",
"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 channel</p>",
"stream_id": 2,
"stream_post_policy": 1,
"stream_weekly_traffic": null,
},
{
"can_remove_subscribers_group": 9,
"creator_id": 12,
"date_created": 1691057093,
"description": "A default public channel",
"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 channel</p>",
"stream_id": 1,
"stream_post_policy": 1,
"stream_weekly_traffic": null,
},
],
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error",
}
description: |
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):
/streams/{stream_id}:
get:
operationId: get-stream-by-id
summary: Get a channel by ID
tags: ["channels"]
description: |
Fetch details for the channel with the ID `stream_id`.
**Changes**: New in Zulip 6.0 (feature level 132).
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
stream:
$ref: "#/components/schemas/BasicChannel"
example:
{
"msg": "",
"result": "success",
"stream":
{
"description": "A Scandinavian country",
"first_message_id": 1,
"history_public_to_subscribers": true,
"date_created": 1691057093,
"creator_id": null,
"invite_only": false,
"is_announcement_only": 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,
"can_remove_subscribers_group": 2,
"stream_weekly_traffic": null,
},
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidChannelError"
- description: |
An example JSON response for when the channel ID is not valid:
delete:
operationId: archive-stream
summary: Archive a channel
tags: ["channels"]
description: |
[Archive the channel](/help/archive-a-channel) with the ID `stream_id`.
x-requires-administrator: true
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidChannelError"
- description: |
An example JSON response for when the supplied channel does not exist:
patch:
operationId: update-stream
summary: Update a channel
tags: ["channels"]
description: |
Configure the channel with the ID `stream_id`. This endpoint supports
an organization administrator editing any property of a channel,
including:
- Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description)
- Channel [permissions](/help/channel-permissions), including
[privacy](/help/change-the-privacy-of-a-channel) and [who can
send](/help/channel-posting-policy).
Note that an organization administrator's ability to change a
[private channel's permissions](/help/channel-permissions#private-channels)
depends on them being subscribed to the channel.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- new_name
- description
- is_private
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
description:
description: |
The new [description](/help/change-the-channel-description) for
the channel, in text/markdown format.
Clients should use the `max_stream_description_length` returned
by the [`POST /register`](/api/register-queue) endpoint to
determine the maximum channel description length.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
type: string
example: "Discuss Italian history and travel destinations."
new_name:
description: |
The new name for 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.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
type: string
example: Italy
is_private:
description: |
Change whether the channel is a private channel.
type: boolean
example: true
is_announcement_only:
deprecated: true
description: |
Whether the channel is limited to announcements.
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
should use `stream_post_policy` instead.
type: boolean
example: true
is_web_public:
description: |
Change whether the channel is a web-public channel.
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
example: true
history_public_to_subscribers:
description: |
Whether the channel's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the channel.
Corresponds to the [shared history](/help/channel-permissions)
option in documentation.
It's an error for this parameter to be false for a public or
web-public channel and when is_private is false.
**Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers`
was silently ignored unless the request also contained either `is_private` or
`is_web_public`.
type: boolean
example: false
is_default_stream:
description: |
Add or remove the channel as a [default channel][default-channel]
for new users joining the organization.
[default-channel]: /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
example: false
stream_post_policy:
$ref: "#/components/schemas/ChannelPostPolicy"
message_retention_days:
$ref: "#/components/schemas/MessageRetentionDays"
can_remove_subscribers_group:
$ref: "#/components/schemas/CanRemoveSubscribersGroupId"
encoding:
is_private:
contentType: application/json
is_announcement_only:
contentType: application/json
is_web_public:
contentType: application/json
history_public_to_subscribers:
contentType: application/json
is_default_stream:
contentType: application/json
stream_post_policy:
contentType: application/json
can_remove_subscribers_group:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvalidChannelError"
- description: |
An example JSON response for when the supplied channel does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid parameters",
"result": "error",
}
description: |
An example JSON response for when invalid combination of channel permission
parameters are passed:
/streams/{stream_id}/email_address:
get:
operationId: get-stream-email-address
summary: Get channel's email address
tags: ["channels"]
description: |
Get email address of a channel.
**Changes**: New in Zulip 8.0 (feature level 226).
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
email:
type: string
description: |
Email address of the channel.
example:
{
"result": "success",
"msg": "",
"email": "test.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidChannelError"
- description: |
An example JSON response for when the requested channel does not exist,
or where the user does not have permission to access the target channel:
/streams/{stream_id}/delete_topic:
post:
operationId: delete-topic
summary: Delete a topic
tags: ["channels"]
description: |
Delete all messages in a topic.
Topics are a field on messages (not an independent data structure), so
deleting all the messages in the topic deletes the topic from Zulip.
Because this endpoint deletes messages in batches, it is possible for
the request to time out after only deleting some messages in the topic.
When this happens, the `complete` boolean field in the success response
will be `false`. Clients should repeat the request when handling such a
response. If all messages in the topic were deleted, then the success
response will return `"complete": true`.
**Changes**: Before Zulip 9.0 (feature level 256), the server never sent
[`stream` op: `update`](/api/get-events#stream-update) events with an
updated `first_message_id` for a channel when the oldest message that
had been sent to it changed.
Before Zulip 8.0 (feature level 211), if the server's
processing was interrupted by a timeout, but some messages in the topic
were deleted, then it would return `"result": "partially_completed"`,
along with a `code` field for an error string, in the success response
to indicate that there was a timeout and that the client should repeat
the request.
As of Zulip 6.0 (feature level 154), instead of returning an error
response when a request times out after successfully deleting some of
the messages in the topic, a success response is returned with
`"result": "partially_completed"` to indicate that some messages were
deleted.
Before Zulip 6.0 (feature level 147), this request did a single atomic
operation, which could time out for very large topics. As of this
feature level, messages are deleted in batches, starting with the newest
messages, so that progress is made even if the request times out and
returns an error.
x-requires-administrator: true
parameters:
- $ref: "#/components/parameters/ChannelIdInPath"
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
topic_name:
description: |
The name of the topic to delete.
type: string
example: new coffee machine
required:
- topic_name
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- complete
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
complete:
type: boolean
description: |
Whether all unread messages were marked as read.
Will be `false` if the request successfully marked
some, but not all, messages as read.
example: {"msg": "", "result": "success", "complete": true}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Must be an organization administrator",
"code": "UNAUTHORIZED_PRINCIPAL",
}
description: |
Error when the user does not have permission
to delete topics in this organization:
/typing:
post:
operationId: set-typing-status
summary: Set "typing" status
tags: ["users"]
description: |
Notify other users whether the current user is
[typing a message][help-typing].
Clients implementing Zulip's typing notifications
protocol should work as follows:
- Send a request to this endpoint with `"op": "start"` when a user
starts composing a message.
- While the user continues to actively type or otherwise interact with
the compose UI (e.g. interacting with the compose box emoji picker),
send regular `"op": "start"` requests to this endpoint, using
`server_typing_started_wait_period_milliseconds` in the
[`POST /register`][api-register] response as the time interval
between each request.
- Send a request to this endpoint with `"op": "stop"` when a user
has stopped using the compose UI for the time period indicated by
`server_typing_stopped_wait_period_milliseconds` in the
[`POST /register`][api-register] response or when a user
cancels the compose action (if it had previously sent a "start"
notification for that compose action).
- Start displaying a visual typing indicator for a given conversation
when a [`typing op:start`][start-typing] event is received
from the server.
- Continue displaying a visual typing indicator for the conversation
until a [`typing op:stop`][stop-typing] event is received
from the server or the time period indicated by
`server_typing_started_expiry_period_milliseconds` in the
[`POST /register`][api-register] response has passed without
a new `typing "op": "start"` event for the conversation.
This protocol is designed to allow the server-side typing notifications
implementation to be stateless while being resilient as network failures
will not result in a user being incorrectly displayed as perpetually
typing.
See the subsystems documentation on [typing indicators][typing-protocol-docs]
for additional design details on Zulip's typing notifications protocol.
**Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215)
for channel typing notifications, as no client actually implemented
the previous API for those.
Support for displaying channel typing notifications was new
in Zulip 4.0 (feature level 58). Clients should indicate they support
processing channel typing notifications via the `stream_typing_notifications`
value in the `client_capabilities` parameter of the
[`POST /register`][client-capabilities] endpoint.
[help-typing]: /help/typing-notifications
[api-register]: /api/register-queue
[start-typing]: /api/get-events#typing-start
[stop-typing]: /api/get-events#typing-stop
[client-capabilities]: /api/register-queue#parameter-client_capabilities
[typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- topic
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
type:
description: |
Type of the message being composed.
**Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as
an additional value for this parameter to indicate a channel message is
being composed.
In Zulip 8.0 (feature level 215), stopped supporting
`"private"` as a valid value for this parameter.
In Zulip 7.0 (feature level 174), `"direct"` was added
as the preferred way to indicate a direct message is being composed,
becoming the default value for this parameter and deprecating the
original `"private"`.
New in Zulip 4.0 (feature level 58). Previously, typing notifications
were only for direct messages.
type: string
enum:
- direct
- stream
- channel
default: direct
example: direct
op:
description: |
Whether the user has started (`"start"`) or stopped (`"stop"`) typing.
type: string
enum:
- start
- stop
example: start
to:
description: |
User IDs of the recipients of the message being typed. Required for the
`"direct"` type. Ignored in the case of `"stream"` or `"channel"` type.
Clients should send a JSON-encoded list of user IDs, even if there is only
one recipient.
**Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter
for the `"stream"` type. Previously, in the case of the `"stream"` type, it
accepted a single-element list containing the ID of the channel. A new parameter,
`stream_id`, is now used for this. Note that the `"channel"` type did not
exist at this feature level.
Support for typing notifications for channel' messages
is new in Zulip 4.0 (feature level 58). Previously, typing
notifications were only for direct messages.
Before Zulip 2.0.0, this parameter accepted only a JSON-encoded
list of email addresses. Support for the email address-based format was
removed in Zulip 3.0 (feature level 11).
type: array
items:
type: integer
minLength: 1
example: [9, 10]
stream_id:
description: |
ID of the channel in which the message is being typed. Required for the `"stream"`
or `"channel"` type. Ignored in the case of `"direct"` type.
**Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element
list containing the ID of the channel was passed in `to` parameter.
type: integer
example: 7
topic:
description: |
Topic to which message is being typed. Required for the `"stream"` or `"channel"`
type. Ignored in the case of `"direct"` type.
**Changes**: New in Zulip 4.0 (feature level 58). Previously, typing
notifications were only for direct messages.
type: string
example: typing notifications
required:
- op
encoding:
to:
contentType: application/json
stream_id:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Missing channel ID",
"result": "error",
}
description: |
An example JSON error response when the user composes a channel message
and `stream_id` is not specified:
/user_groups/create:
post:
operationId: create-user-group
summary: Create a user group
tags: ["users"]
description: |
Create a new [user group](/help/user-groups).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
description: |
The name of the user group.
type: string
example: marketing
description:
description: |
The description of the user group.
type: string
example: The marketing team.
members:
description: |
An array containing the user IDs of the initial members for the
new user group.
type: array
items:
type: integer
example: [1, 2, 3, 4]
can_mention_group:
allOf:
- description: |
A [group-setting value][setting-values] defining the set of users who
have permission to [mention this user group][mentions].
This setting cannot be set to `"role:internet"` and `"role:owners"`
[system groups][system-groups].
Before Zulip 9.0 (feature level 258), this parameter could only be the
integer form of a [group-setting value][setting-values].
Before Zulip 8.0 (feature level 198), this parameter was named
`can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups could be
mentioned only if they were not [system groups][system-groups].
[setting-values]: /api/group-setting-values
[system-groups]: /api/group-setting-values#system-groups
[mentions]: /help/mention-a-user-or-group
- $ref: "#/components/schemas/GroupSettingValue"
example: 11
required:
- name
- description
- members
encoding:
members:
contentType: application/json
can_mention_group:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"code": "BAD_REQUEST",
"msg": "Invalid user ID: 500",
}
description: |
An example JSON error response for when the one of the users does not exist:
/user_groups/{user_group_id}/members:
post:
operationId: update-user-group-members
summary: Update user group members
tags: ["users"]
description: |
Update the members of a [user group](/help/user-groups).
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- delete
parameters:
- $ref: "#/components/parameters/UserGroupId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
delete:
description: |
The list of user IDs to be removed from the user group.
type: array
items:
type: integer
example: [10]
add:
description: |
The list of user IDs to be added to the user group.
type: array
items:
type: integer
example: [12, 13]
encoding:
delete:
contentType: application/json
add:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
get:
operationId: get-user-group-members
summary: Get user group members
tags: ["users"]
description: |
Get the members of a [user group](/help/user-groups).
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- $ref: "#/components/parameters/DirectMemberOnly"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
members:
type: array
items:
type: integer
description: |
A list containing the user IDs of members of the user group.
example:
{"msg": "", "result": "success", "members": [10, 12]}
/user_groups/{user_group_id}:
patch:
operationId: update-user-group
summary: Update a user group
tags: ["users"]
description: |
Update the name or description of a [user group](/help/user-groups).
parameters:
- $ref: "#/components/parameters/UserGroupId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
description: |
The new name of the group.
**Changes**: Before Zulip 7.0 (feature level 165), this was
a required field.
type: string
example: marketing team
description:
description: |
The new description of the group.
**Changes**: Before Zulip 7.0 (feature level 165), this was
a required field.
type: string
example: The marketing team.
can_mention_group:
description: |
The set of users who have permission to [mention this group][mentions],
expressed as an [update to a group-setting value][update-group-setting].
This setting cannot be set to `"role:internet"` and `"role:owners"`
[system groups][system-groups].
**Changes**: In Zulip 9.0 (feature level 260), this parameter was
updated to only accept an object with the `old` and `new` fields
described below. Prior to this feature level, this parameter could be
either of the two forms of a [group-setting value][setting-values].
Before Zulip 9.0 (feature level 258), this parameter could only be the
integer form of a [group-setting value][setting-values].
Before Zulip 8.0 (feature level 198), this parameter was named
`can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups could be
mentioned only if they were not [system groups][system-groups].
[mentions]: /help/mention-a-user-or-group
[update-group-setting]: /api/group-setting-values#updating-group-setting-values
[system-groups]: /api/group-setting-values#system-groups
[setting-values]: /api/group-setting-values
type: object
additionalProperties: false
properties:
new:
allOf:
- description: |
The new [group-setting value](/api/group-setting-values) for who would
have the permission to mention the group.
- $ref: "#/components/schemas/GroupSettingValue"
old:
allOf:
- description: |
The expected current [group-setting value](/api/group-setting-values)
for who has the permission to mention the group.
- $ref: "#/components/schemas/GroupSettingValue"
required:
- new
example:
{
"new": {"direct_members": [10], "direct_subgroups": [11]},
"old": 11,
}
encoding:
can_mention_group:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error",
}
description: |
An example JSON response when the user group ID is invalid:
delete:
operationId: remove-user-group
summary: Delete a user group
tags: ["users"]
description: |
Delete a [user group](/help/user-groups).
parameters:
- $ref: "#/components/parameters/UserGroupId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error",
}
description: |
An example JSON error response for an invalid user group ID:
/user_groups:
get:
operationId: get-user-groups
summary: Get user groups
tags: ["users"]
description: |
Fetches all of the user groups in the organization.
!!! warn ""
**Note**: This endpoint is only available to [members and
administrators](/help/roles-and-permissions); bots and guests
cannot use this endpoint.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user_groups:
type: array
items:
type: object
additionalProperties: false
properties:
description:
type: string
description: |
The human-readable description of the user group.
id:
type: integer
description: |
The user group's integer ID.
members:
type: array
description: |
The integer user IDs of the user group members.
items:
type: integer
direct_subgroup_ids:
type: array
description: |
The integer user group IDs of the direct subgroups.
**Changes**: New in Zulip 6.0 (feature level 131).
Introduced in feature level 127 as `subgroups`, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
items:
type: integer
name:
type: string
description: |
User group name.
is_system_group:
type: boolean
description: |
Whether the user group is a system group which cannot be
modified by users.
**Changes**: New in Zulip 5.0 (feature level 93).
can_mention_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value][setting-values] defining the set of users who
have permission to [mention this user group][mentions].
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
always the integer form of a [group-setting value][setting-values].
Before Zulip 8.0 (feature level 198), this setting was named
`can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups could be
mentioned only if they were not [system groups][system-groups].
Will be one of the following:
[setting-values]: /api/group-setting-values
[system-groups]: /api/group-setting-values#system-groups
[mentions]: /help/mention-a-user-or-group
description: |
A list of `user_group` objects.
example:
{
"msg": "",
"result": "success",
"user_groups":
[
{
"description": "Owners of this organization",
"id": 1,
"name": "role:owners",
"members": [1],
"direct_subgroup_ids": [],
"is_system_group": true,
"can_mention_group": 11,
},
{
"description": "Administrators of this organization, including owners",
"id": 2,
"name": "role:administrators",
"members": [2],
"direct_subgroup_ids": [1],
"is_system_group": true,
"can_mention_group": 12,
},
{
"description": "Characters of Hamlet",
"id": 3,
"name": "hamletcharacters",
"members": [3, 4],
"direct_subgroup_ids": [],
"is_system_group": false,
"can_mention_group": 13,
},
],
}
/user_groups/{user_group_id}/subgroups:
post:
operationId: update-user-group-subgroups
summary: Update subgroups of a user group
tags: ["users"]
description: |
Update the subgroups of a [user group](/help/user-groups).
**Changes**: New in Zulip 6.0 (feature level 127).
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- delete
parameters:
- $ref: "#/components/parameters/UserGroupId"
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
delete:
description: |
The list of user group IDs to be removed from the user group.
type: array
items:
type: integer
example: [10]
add:
description: |
The list of user group IDs to be added to the user group.
type: array
items:
type: integer
example: [9, 10]
encoding:
delete:
contentType: application/json
add:
contentType: application/json
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
get:
operationId: get-user-group-subgroups
summary: Get subgroups of a user group
tags: ["users"]
description: |
Get the subgroups of a [user group](/help/user-groups).
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- name: direct_subgroup_only
in: query
description: |
Whether to consider only direct subgroups of the user group
or subgroups of subgroups also.
schema:
type: boolean
default: false
example: true
required: false
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
subgroups:
type: array
items:
type: integer
description: |
A list containing the IDs of subgroups of the user group.
example:
{"msg": "", "result": "success", "subgroups": [2, 3]}
/user_groups/{user_group_id}/members/{user_id}:
get:
operationId: get-is-user-group-member
summary: Get user group membership status
tags: ["users"]
description: |
Check whether a user is member of user group.
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/DirectMemberOnly"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
is_user_group_member:
type: boolean
description: |
Whether the user is member of user group.
example:
{
"msg": "",
"result": "success",
"is_user_group_member": false,
}
/real-time:
# This entry is a hack; it exists to give us a place to put the text
# documenting the parameters for call_on_each_event and friends.
post:
tags: ["real_time_events"]
description: |
(Ignored)
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
event_types:
$ref: "#/components/schemas/Event_types"
narrow:
$ref: "#/components/schemas/Narrow"
all_public_streams:
$ref: "#/components/schemas/AllPublicChannels"
encoding:
event_types:
contentType: application/json
narrow:
contentType: application/json
all_public_streams:
contentType: application/json
security:
- basicAuth: []
responses:
# Makeshift response for this hack entry.
"200":
description: Success
/rest-error-handling:
post:
operationId: rest-error-handling
summary: Error handling
tags: ["real_time_events"]
description: |
Common error to many endpoints
responses:
"400":
description: |
Bad request.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/InvalidApiKeyError"
- $ref: "#/components/schemas/MissingArgumentError"
- $ref: "#/components/schemas/IncompatibleParametersError"
- $ref: "#/components/schemas/UserNotAuthorizedError"
"401":
description: |
Unauthorized.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/UserDeactivatedError"
- $ref: "#/components/schemas/RealmDeactivatedError"
"429":
description: |
Rate limit exceeded.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RateLimitedError"
/zulip-outgoing-webhook:
post:
operationId: zulip-outgoing-webhooks
summary: Outgoing webhooks
tags: ["webhooks"]
description: |
Outgoing webhooks allow you to build or set up Zulip integrations which are
notified when certain types of messages are sent in Zulip.
responses:
"200":
description: |
Success
content:
application/json:
schema:
type: object
additionalProperties: false
description: |
This is an example of the JSON payload that the Zulip server will `POST`
to your server:
properties:
bot_email:
type: string
description: |
Email of the bot user.
bot_full_name:
type: string
description: |
The full name of the bot user.
data:
type: string
description: |
The message content, in raw Markdown format (not rendered to HTML).
trigger:
type: string
description: |
What aspect of the message triggered the outgoing webhook notification.
Possible values include `direct_message` and `mention`.
**Changes**: In Zulip 8.0 (feature level 201), renamed the trigger
`private_message` to `direct_message`.
token:
type: string
description: |
A string of alphanumeric characters that can be used to authenticate the
webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot
in the `zuliprc` file downloaded when creating the bot.
message:
description: |
A dictionary containing details on the message that triggered the
outgoing webhook, in the format used by [`GET /messages`](/api/get-messages).
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
rendered_content:
type: string
description: |
The content/body of the message rendered in HTML.
example:
{
"data": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
"trigger": "mention",
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
"message":
{
"subject": "Verona2",
"sender_email": "iago@zulip.com",
"timestamp": 1527876931,
"client": "website",
"submessages": [],
"recipient_id": 20,
"topic_links": [],
"sender_full_name": "Iago",
"avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
"rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing webhook test</span> Zulip is the world\u2019s most productive group chat!</p>",
"sender_id": 5,
"stream_id": 5,
"content": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
"display_recipient": "Verona",
"type": "stream",
"id": 112,
"is_me_message": false,
"reactions": [],
"sender_realm_str": "zulip",
},
"bot_email": "outgoing-bot@localhost",
"bot_full_name": "Outgoing webhook test",
}
/calls/bigbluebutton/create:
get:
tags: ["channels"]
operationId: create-big-blue-button-video-call
summary: Create BigBlueButton video call
description: |
Create a video call URL for a BigBlueButton video call.
Requires [BigBlueButton](/integrations/doc/big-blue-button)
to be configured on the Zulip server.
parameters:
- in: query
name: meeting_name
schema:
type: string
required: true
description: |
Meeting name for the BigBlueButton video call.
example: "test_channel meeting"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
url:
description: |
The URL for the BigBlueButton video call.
type: string
example: "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22"
example:
{
"msg": "",
"result": "success",
"url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22",
}
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: |
Basic authentication, with the user's email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
schemas:
IgnoredParametersUnsupported:
type: array
items:
type: string
description: |
An array of any parameters sent in the request that are not
supported by the endpoint.
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
for details on this and its change history.
EventIdSchema:
type: integer
description: |
The ID of the event. Events appear in increasing order but may not be consecutive.
EventTypeSchema:
type: string
description: |
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in [POST /register](/api/register-queue).
Anchor:
type: string
Attachments:
type: object
description: |
Dictionary containing details of a file uploaded by a user.
additionalProperties: false
properties:
id:
type: integer
description: |
The unique ID for the attachment.
name:
type: string
description: |
Name of the uploaded file.
path_id:
type: string
description: |
A representation of the path of the file within the
repository of user-uploaded files. If the `path_id` of a
file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
size:
type: integer
description: |
Size of the file in bytes.
create_time:
type: integer
description: |
Time when the attachment was uploaded as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 3.0 (feature level 22). This field was
previously a floating point number.
messages:
type: array
description: |
Contains basic details on any Zulip messages that have been
sent referencing this [uploaded file](/api/upload-file).
This includes messages sent by any user in the Zulip
organization who sent a message containing a link to the
uploaded file.
items:
type: object
additionalProperties: false
properties:
date_sent:
type: integer
description: |
Time when the message was sent as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 3.0 (feature level 22). This
field was previously strangely called `name` and was a floating
point number.
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
BasicChannel:
allOf:
- $ref: "#/components/schemas/BasicChannelBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
creator_id:
nullable: true
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
can_remove_subscribers_group: {}
stream_weekly_traffic:
type: integer
nullable: true
description: |
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.
required:
- stream_id
- name
- description
- date_created
- creator_id
- invite_only
- rendered_description
- is_web_public
- stream_post_policy
- message_retention_days
- history_public_to_subscribers
- first_message_id
- is_announcement_only
- can_remove_subscribers_group
- stream_weekly_traffic
DefaultChannel:
allOf:
- $ref: "#/components/schemas/BasicChannelBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
creator_id:
nullable: true
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
can_remove_subscribers_group: {}
required:
- stream_id
- name
- description
- date_created
- creator_id
- invite_only
- rendered_description
- is_web_public
- stream_post_policy
- message_retention_days
- history_public_to_subscribers
- first_message_id
- is_announcement_only
- can_remove_subscribers_group
BasicChannelBase:
type: object
description: |
Object containing basic details about the channel.
properties:
stream_id:
type: integer
description: |
The unique ID of the channel.
name:
type: string
description: |
The name of the channel.
description:
type: string
description: |
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:
type: integer
description: |
The UNIX timestamp for when the channel was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
creator_id:
type: integer
nullable: true
description: |
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][management-commands].
**Changes**: New in Zulip 9.0 (feature level 254).
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
invite_only:
type: boolean
description: |
Specifies whether the channel is private or not.
Only people who have been invited can access a private channel.
rendered_description:
type: string
description: |
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:
type: boolean
description: |
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:
type: integer
description: |
[Policy][permission-level] for which users can post messages to the channel.
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only [full members][calc-full-member] can post.
- 4 = Only moderators can post.
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this channel will be stored
before being automatically deleted by the [message retention
policy](/help/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:
type: boolean
description: |
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:
type: integer
nullable: true
description: |
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:
type: boolean
deprecated: true
description: |
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:
type: integer
description: |
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).
BasicBot:
allOf:
- $ref: "#/components/schemas/BasicBotBase"
- additionalProperties: false
properties:
user_id: {}
full_name: {}
api_key: {}
default_sending_stream:
nullable: true
default_events_register_stream:
nullable: true
default_all_public_streams: {}
avatar_url: {}
owner_id:
nullable: true
services: {}
is_active:
type: boolean
description: |
A boolean describing whether the user account has been deactivated.
**Changes**: New in Zulip 8.0 (feature level 222). Previously
we sent `realm_user` event with `op` field set to `remove`
when deactivating a bot and `realm_user` event with `op`
field set to `add` when reactivating a bot.
BasicBotBase:
type: object
properties:
user_id:
type: integer
description: |
The user ID of the bot.
full_name:
type: string
description: |
The full name of the bot.
api_key:
type: string
description: |
The API key of the bot which it uses to make API requests.
default_sending_stream:
type: string
nullable: true
description: |
The default sending channel of the bot. If `null`, the bot doesn't
have a default sending channel.
default_events_register_stream:
type: string
nullable: true
description: |
The default channel for which the bot receives events/register data.
If `null`, the bot doesn't have such a default channel.
default_all_public_streams:
type: boolean
description: |
Whether the bot can send messages to all channels by default.
avatar_url:
type: string
description: |
The URL of the bot's avatar.
owner_id:
type: integer
nullable: true
description: |
The user ID of the bot's owner.
If `null`, the bot has no owner.
services:
type: array
description: |
An array containing extra configuration fields only relevant for
outgoing webhook bots and embedded bots. This is always a single-element
array.
We consider this part of the Zulip API to be unstable; it is used only
for UI elements for administering bots and is likely to change.
items:
description: |
Object with extra configuration details for the bot. The fields in the
object depend on the type of bot.
oneOf:
- type: object
additionalProperties: false
description: |
When the bot is an outgoing webhook.
properties:
base_url:
type: string
description: |
The URL the outgoing webhook is configured to post to.
token:
type: string
description: |
A unique token that the third-party service can use to confirm
that the request is indeed coming from Zulip.
interface:
type: integer
description: |
An integer indicating what format requests are posted in:
- 1 = Zulip's native outgoing webhook format.
- 2 = Emulate the Slack outgoing webhook format.
- type: object
additionalProperties: false
description: |
When the bot is an embedded bot.
properties:
service_name:
type: string
description: |
The name of the bot.
config_data:
$ref: "#/components/schemas/BotConfiguration"
Bot:
allOf:
- $ref: "#/components/schemas/BasicBotBase"
- description: |
Object containing details of a bot.
additionalProperties: false
properties:
user_id: {}
full_name: {}
api_key: {}
default_sending_stream:
nullable: true
default_events_register_stream:
nullable: true
default_all_public_streams: {}
avatar_url: {}
owner_id:
nullable: true
services: {}
email:
type: string
description: |
The email of the bot.
bot_type:
type: integer
nullable: true
description: |
An integer describing the type of bot:
- `1` for a `Generic` bot.
- `2` for an `Incoming webhook` bot.
- `3` for an `Outgoing webhook` bot.
- `4` for an `Embedded` bot.
is_active:
type: boolean
description: |
A boolean describing whether the user account has been deactivated.
BotConfiguration:
type: object
description: |
A dictionary of string key/value pairs, which describe the configuration
for the bot. These are usually details like API keys, and are unique to
the integration/bot. Can be an empty dictionary.
additionalProperties:
description: |
`{config_key}`: Description/value of the configuration data key.
type: string
CustomProfileField:
type: object
additionalProperties: false
description: |
Dictionary containing the details of a custom profile field configured
for this organization.
properties:
id:
type: integer
description: |
The ID of the custom profile field. This will be referenced in the custom
profile fields section of user objects.
type:
type: integer
description: |
An integer indicating the type of the custom profile field, which determines
how it is configured and displayed to users.
See the [Custom profile fields](/help/custom-profile-fields#profile-field-types)
article for details on what each type means.
- **1**: Short text
- **2**: Long text
- **3**: List of options
- **4**: Date picker
- **5**: Link
- **6**: Person picker
- **7**: External account
- **8**: Pronouns
**Changes**: Field type `8` added in Zulip 6.0 (feature level 151).
order:
type: integer
description: |
Custom profile fields are displayed in both settings UI and
UI showing users' profiles in increasing `order`.
name:
type: string
description: |
The name of the custom profile field.
hint:
type: string
description: |
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
field_data:
type: string
description: |
Field types 3 (List of options) and 7 (External account) support storing
additional configuration for the field type in the `field_data` attribute.
For field type 3 (List of options), this attribute is a JSON dictionary
defining the choices and the order they will be displayed in the
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
display_in_profile_summary:
type: boolean
description: |
Whether the custom profile field, display or not on the user card.
Currently it's value not allowed to be `true` of `Long text` and `Person picker`
[profile field types](/help/custom-profile-fields#profile-field-types).
This field is only included when its value is `true`.
**Changes**: New in Zulip 6.0 (feature level 146).
default: false
required:
type: boolean
description: |
Whether an organization administrator has configured this profile field as
required.
Because the required property is mutable, clients cannot assume that a required
custom profile field has a value. The Zulip web application displays a prominent
banner to any user who has not set a value for a required field.
**Changes**: New in Zulip 9.0 (feature level 244).
required:
- id
- type
- order
- name
- hint
- required
OnboardingStep:
type: object
additionalProperties: false
description: |
Dictionary containing details of a single onboarding step.
properties:
type:
type: string
description: |
The type of the onboarding step. Valid value is `"one_time_notice"`.
**Changes**: Removed type `"hotspot"` in Zulip 9.0 (feature level 259).
New in Zulip 8.0 (feature level 233).
name:
type: string
description: |
The name of the onboarding step.
RealmAuthenticationMethod:
type: object
properties:
enabled:
type: boolean
description: |
Boolean describing whether the authentication method (i.e. its key)
is enabled in this organization.
available:
type: boolean
description: |
Boolean describing whether the authentication method is available for use.
If false, the organization is not eligible to enable the authentication
method.
unavailable_reason:
type: string
description: |
Reason why the authentication method is unavailable. This field is optional
and is only present when 'available' is false.
additionalProperties: false
description: |
Dictionary describing the properties of an authentication method for the
organization - its enabled status and availability for use by the
organization.
RealmEmoji:
type: object
additionalProperties: false
description: |
`{emoji_id}`: Object containing details about the emoji with
the specified ID. It has the following properties:
properties:
id:
type: string
description: |
The ID for this emoji, same as the object's key.
name:
type: string
description: |
The user-friendly name for this emoji. Users in the organization
can use this emoji by writing this name between colons (`:name :`).
source_url:
type: string
description: |
The path relative to the organization's URL where the
emoji's image can be found.
still_url:
type: string
nullable: true
description: |
Only non-null when the emoji's image is animated.
The path relative to the organization's URL where a still
(not animated) version of the emoji can be found. (This is
currently always the first frame of the animation).
This is useful for clients to display the emoji in contexts
where continuously animating it would be a bad user experience
(E.g. because it would be distracting).
**Changes**: New in Zulip 5.0 (added as optional field in
feature level 97 and then made mandatory, but nullable, in
feature level 113).
deactivated:
type: boolean
description: |
Whether the emoji has been deactivated or not.
author_id:
type: integer
nullable: true
description: |
The user ID of the user who uploaded the custom emoji.
Will be `null` if the uploader is unknown.
**Changes**: New in Zulip 3.0 (feature level 7). Previously
was accessible via an `author` object with an `id` field.
RealmDomain:
type: object
additionalProperties: false
description: |
Object containing details of the newly added domain.
properties:
domain:
type: string
description: |
The new allowed domain.
allow_subdomains:
type: boolean
description: |
Whether subdomains are allowed for this domain.
RealmPlayground:
type: object
additionalProperties: false
description: |
Object containing details about a realm playground.
properties:
id:
type: integer
description: |
The unique ID for the realm playground.
name:
type: string
description: |
The user-visible display name of the playground. Clients
should display this in UI for picking which playground to
open a code block in, to differentiate between multiple
configured playground options for a given pygments
language.
**Changes**: New in Zulip 4.0 (feature level 49).
pygments_language:
type: string
description: |
The name of the Pygments language lexer for that
programming language.
url_template:
type: string
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
compliant URL template for the playground. The template contains
exactly one variable named `code`, which determines how the
extracted code should be substituted in the playground URL.
**Changes**: New in Zulip 8.0 (feature level 196). This replaced the
`url_prefix` parameter, which was used to construct URLs by just
concatenating url_prefix and code.
RealmExport:
type: object
additionalProperties: false
description: |
Object containing details about a
[data export](/help/export-your-organization).
properties:
id:
type: integer
description: |
The ID of the data export.
acting_user_id:
type: integer
description: |
The ID of the user who created the data export.
export_time:
type: number
description: |
The UNIX timestamp of when the data export was started.
deleted_timestamp:
type: number
nullable: true
description: |
The UNIX timestamp of when the data export was deleted.
Will be `null` if the data export has not been deleted.
failed_timestamp:
type: number
nullable: true
description: |
The UNIX timestamp of when the data export failed.
Will be `null` if the data export succeeded, or if it's
still being generated.
export_url:
type: string
nullable: true
description: |
The URL to download the generated data export.
Will be `null` if the data export failed, or if it's
still being generated.
pending:
type: boolean
description: |
Whether the data export is pending, which indicates it
is still being generated, or if it succeeded, failed or
was deleted before being generated.
Depending on the size of the organization, it can take
anywhere from seconds to an hour to generate the data
export.
UserGroup:
type: object
additionalProperties: false
description: |
Object containing the user group's attributes.
properties:
name:
type: string
description: |
The name of the user group.
description:
type: string
description: |
The description of the user group.
members:
type: array
items:
type: integer
description: |
Array containing the ID of the users who are
members of this user group.
direct_subgroup_ids:
type: array
items:
type: integer
description: |
Array containing the ID of the direct_subgroups of
this user group.
**Changes**: New in Zulip 6.0 (feature level 131).
Introduced in feature level 127 as `subgroups`, but
clients can ignore older events as this feature level
predates subgroups being fully implemented.
id:
type: integer
description: |
The ID of the user group.
is_system_group:
type: boolean
description: |
Whether the user group is a system group which cannot be
directly modified by users.
**Changes**: New in Zulip 5.0 (feature level 93).
can_mention_group:
allOf:
- $ref: "#/components/schemas/GroupSettingValue"
- description: |
A [group-setting value][setting-values] defining the set of users who
have permission to [mention this user group][mentions].
**Changes**: Before Zulip 9.0 (feature level 258), this setting was
always the integer form of a [group-setting value][setting-values].
Before Zulip 8.0 (feature level 198), this setting was named
`can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups could be
mentioned only if they were not [system groups][system-groups].
Will be one of the following:
[setting-values]: /api/group-setting-values
[system-groups]: /api/group-setting-values#system-groups
[mentions]: /help/mention-a-user-or-group
GroupSettingValue:
oneOf:
- type: integer
description: |
The ID of the [user group](/help/user-groups) with this permission.
- type: object
additionalProperties: false
properties:
direct_members:
description: |
The list of IDs of individual users in the collection of users with this permission.
type: array
items:
type: integer
direct_subgroups:
description: |
The list of IDs of the groups in the collection of users with this permission.
type: array
items:
type: integer
description: |
An object with these fields:
Invite:
type: object
description: |
A dictionary containing details about an [invitation](/help/invite-new-users).
additionalProperties: false
properties:
id:
type: integer
description: |
The ID of the invitation.
Note that email invitations and reusable invitation links are stored
in different database tables on the server, so each ID is guaranteed
to be unique in combination with the boolean value of `is_multiuse`,
e.g. there can only be one invitation with `id: 1` and `is_multiuse:
true`.
invited_by_user_id:
type: integer
description: |
The [user ID](/api/get-user) of the user who created the invitation.
**Changes**: New in Zulip 3.0 (feature level 22), replacing the `ref`
field which contained the Zulip display email address of the user who
created the invitation.
invited:
type: integer
description: |
The UNIX timestamp for when the invitation was created, in UTC seconds.
expiry_date:
type: integer
nullable: true
description: |
The UNIX timestamp for when the invitation will expire, in UTC seconds.
If `null`, the invitation never expires.
invited_as:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: |
The [organization-level role](/api/roles-and-permissions) of the user that
is created when the invitation is accepted.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
email:
type: string
description: |
The email address the invitation was sent to. This will not be present when
`is_multiuse` is `true` (i.e. the invitation is a reusable invitation link).
notify_referrer_on_join:
type: boolean
description: |
A boolean indicating whether the referrer has opted to receive a direct
message from [notification bot](/help/configure-automated-notices) when a user
account is created using this invitation.
**Changes**: New in Zulip 9.0 (feature level 267). Previously,
referrers always received such direct messages.
link_url:
type: string
description: |
The URL of the reusable invitation link. This will not be present when
`is_multiuse` is `false` (i.e. the invitation is an email invitation).
is_multiuse:
type: boolean
description: |
A boolean specifying whether the [invitation](/help/invite-new-users) is a
reusable invitation link or an email invitation.
InviteExpirationParameter:
description: |
The number of minutes before the invitation will expire. If `null`, the
invitation will never expire. If unspecified, the server will use a default
value (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which
defaults to 14400, i.e. 10 days) for when the invitation will expire.
**Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an
`invite_expires_in_days` parameter, which specified the duration in days instead
of minutes.
type: integer
nullable: true
example: 14400
InviteRoleParameter:
description: |
The [organization-level role](/api/roles-and-permissions) of the user that is
created when the invitation is accepted.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
Users can only create invitation links for
[roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels)
as their own. For example, a moderator cannot invite someone to be an owner
or administrator, but they can invite them to be a moderator or member.
**Changes**: In Zulip 4.0 (feature level 61), added support for inviting
users as moderators.
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
default: 400
example: 600
Subscriptions:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a channel.
name:
type: string
description: |
The name of a channel.
description:
type: string
description: |
The [description](/help/change-the-channel-description) of the channel in text/markdown format,
intended to be used to prepopulate UI for editing a channel's
description.
See also `rendered_description`.
rendered_description:
type: string
description: |
The [description](/help/change-the-channel-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.
See also `description`.
date_created:
type: integer
description: |
The UNIX timestamp for when the channel was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
creator_id:
type: integer
nullable: true
description: |
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][management-commands].
**Changes**: New in Zulip 9.0 (feature level 254).
[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html
invite_only:
type: boolean
description: |
Specifies whether the channel is private or not.
Only people who have been invited can access a private channel.
# TODO: This subscribers item should probably be declared optional more
# explicitly in the OpenAPI format?
subscribers:
type: array
items:
type: integer
description: |
A list of user IDs of users who are also subscribed
to a given channel. Included only if `include_subscribers` is `true`.
desktop_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether desktop notifications
are enabled for the given channel.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, `enable_stream_desktop_notifications`, for
this channel.
email_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether email notifications
are enabled for the given channel.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, `enable_stream_email_notifications`, for
this channel.
wildcard_mentions_notify:
type: boolean
nullable: true
description: |
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this channel.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this channel.
push_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether push notifications
are enabled for the given channel.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, `enable_stream_push_notifications`, for
this channel.
audible_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether audible notifications
are enabled for the given channel.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, `enable_stream_audible_notifications`, for
this channel.
pin_to_top:
type: boolean
description: |
A boolean specifying whether the given channel has been pinned
to the top.
is_muted:
type: boolean
description: |
Whether the user has muted the channel. Muted channels do
not count towards your total unread count and do not show
up in the `Combined feed` view (previously known as `All messages`).
**Changes**: Prior to Zulip 2.1.0, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`).
in_home_view:
type: boolean
deprecated: true
description: |
Legacy property for if the given channel is muted, with inverted meaning.
**Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted`
where available.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether only organization administrators can post to the channel.
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
should use `stream_post_policy` instead.
is_web_public:
type: boolean
description: |
Whether the channel has been configured to allow unauthenticated
access to its message history from the web.
color:
type: string
description: |
The user's personal color for the channel.
stream_post_policy:
type: integer
description: |
[Policy][permission-level] for which users can post messages to the channel.
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only [full members][calc-full-member] can post.
- 4 = Only moderators can post.
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this channel will be stored
before being automatically deleted by the [message retention
policy](/help/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:
type: boolean
description: |
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:
type: integer
nullable: true
description: |
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.
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the channel per week, as
estimated based on recent weeks, rounded to the nearest integer.
If `null`, the channel was recently created and there is
insufficient data to estimate the average traffic.
can_remove_subscribers_group:
type: integer
description: |
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).
DefaultChannelGroup:
type: object
description: |
Dictionary containing details of a default channel
group.
additionalProperties: false
properties:
name:
type: string
description: |
Name of the default channel group.
description:
type: string
description: |
Description of the default channel group.
id:
type: integer
description: |
The ID of the default channel group.
streams:
type: array
description: |
Array containing details about the channels
in the default channel group.
items:
$ref: "#/components/schemas/DefaultChannel"
EmailAddressVisibility:
type: integer
description: |
The [policy][permission-level] for [which other users][help-email-visibility]
in this organization can see the user's real email address.
- 1 = Everyone
- 2 = Members only
- 3 = Administrators only
- 4 = Nobody
- 5 = Moderators only
**Changes**: New in Zulip 7.0 (feature level 163), replacing the
realm-level setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[help-email-visibility]: /help/configure-email-visibility
EmojiReaction:
allOf:
- $ref: "#/components/schemas/EmojiBase"
- additionalProperties: false
properties:
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id:
type: integer
description: |
The ID of the user who added the reaction.
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
object is deprecated and will be removed in the future.
user:
type: object
additionalProperties: false
deprecated: true
description: |
Dictionary with data on the user who added the
reaction, including the user ID as the `id`
field. Note that reactions data received from the
[events API](/api/get-events) has a slightly different
`user` dictionary format, with the user ID field
called `user_id` instead.
**Changes**: Deprecated and to be removed in a future release
once core clients have migrated to use the adjacent `user_id`
field, which was introduced in Zulip 3.0 (feature level 2).
Clients supporting older Zulip server versions should use
the user ID mentioned in the description above as they would
the `user_id` field.
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Zulip API email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
EmojiBase:
type: object
properties:
emoji_name:
type: string
description: |
Name of the emoji.
emoji_code:
type: string
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
reaction_type:
type: string
enum:
- unicode_emoji
- realm_emoji
- zulip_extra_emoji
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
EmojiReactionEvent:
allOf:
- $ref: "#/components/schemas/EmojiBase"
- properties:
user_id:
type: integer
description: |
The ID of the user who added the reaction.
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
object is deprecated and will be removed in the future.
user:
type: object
additionalProperties: false
deprecated: true
description: |
Dictionary with data on the user who added the
reaction, including the user ID as the `user_id`
field.
**Changes**: Deprecated and to be removed in a future release
once core clients have migrated to use the adjacent `user_id`
field, which was introduced in Zulip 3.0 (feature level 2).
Clients supporting older Zulip server versions should use
the user ID mentioned in the description above as they would
the `user_id` field.
properties:
user_id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Zulip API email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
MessagesEvent:
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
MessagesBase:
type: object
description: |
Object containing details of the message.
properties:
avatar_url:
type: string
nullable: true
description: |
The URL of the message sender's avatar. Can be `null` only if
the current user has access to the sender's real email address
and `client_gravatar` was `true`.
If `null`, then the sender has not uploaded an avatar in Zulip,
and the client can compute the gravatar URL by hashing the
sender's email address, which corresponds in this case to their
real email address.
**Changes**: Before Zulip 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, `email_address_visibility` is a user setting.
client:
type: string
description: |
A Zulip "client" string, describing what Zulip client
sent the message.
content:
type: string
description: |
The content/body of the message.
content_type:
type: string
description: |
The HTTP `content_type` for the message content. This
will be `text/html` or `text/x-markdown`, depending on
whether `apply_markdown` was set.
display_recipient:
oneOf:
- type: string
- type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Zulip API email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
description: |
Data on the recipient of the message;
either the name of a channel or a dictionary containing basic data on
the users who received the message.
edit_history:
type: array
items:
type: object
additionalProperties: false
properties:
prev_content:
type: string
description: |
Only present if message's content was edited.
The content of the message immediately prior to this
edit event.
prev_rendered_content:
type: string
description: |
Only present if message's content was edited.
The rendered HTML representation of `prev_content`.
prev_rendered_content_version:
type: integer
description: |
Only present if message's content was edited.
The Markdown processor version number for the message
immediately prior to this edit event.
prev_stream:
type: integer
description: |
Only present if message's channel was edited.
The channel ID of the message immediately prior to this
edit event.
**Changes**: New in Zulip 3.0 (feature level 1).
prev_topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately prior to this
edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
Previously, this field was called `prev_subject`;
clients are recommended to rename `prev_subject` to
`prev_topic` if present for compatibility with
older Zulip servers.
stream:
type: integer
description: |
Only present if message's channel was edited.
The ID of the channel containing the message
immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
timestamp:
type: integer
description: |
The UNIX timestamp for the edit.
topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
user_id:
type: integer
nullable: true
description: |
The ID of the user that made the edit.
Will be `null` only for edit history
events predating March 2017.
Clients can display edit history events where this
is `null` as modified by either the sender (for content
edits) or an unknown user (for topic edits).
required:
- user_id
- timestamp
description: |
An array of objects, with each object documenting the
changes in a previous edit made to the message,
ordered chronologically from most recent to least recent
edit.
Not present if the message has never been edited or if the realm has
[disabled viewing of message edit history][disable-edit-history].
Every object will contain `user_id` and `timestamp`.
The other fields are optional, and will be present or not
depending on whether the channel, topic, and/or message
content were modified in the edit event. For example, if
only the topic was edited, only `prev_topic` and `topic`
will be present in addition to `user_id` and `timestamp`.
[disable-edit-history]: /help/disable-message-edit-history
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
is_me_message:
type: boolean
description: |
Whether the message is a [/me status message][status-messages]
[status-messages]: /help/format-your-message-using-markdown#status-messages
last_edit_timestamp:
type: integer
description: |
The UNIX timestamp for when the message was last edited,
in UTC seconds.
Not present if the message has never been edited.
reactions:
type: array
description: |
Data on any reactions to the message.
items:
$ref: "#/components/schemas/EmojiReaction"
recipient_id:
type: integer
description: |
A unique ID for the set of users receiving the
message (either a channel or group of users). Useful primarily
for hashing.
sender_email:
type: string
description: |
The Zulip API email address of the message's sender.
sender_full_name:
type: string
description: |
The full name of the message's sender.
sender_id:
type: integer
description: |
The user ID of the message's sender.
sender_realm_str:
type: string
description: |
A string identifier for the realm the sender is in. Unique only within
the context of a given Zulip server.
E.g. on `example.zulip.com`, this will be `example`.
stream_id:
type: integer
description: |
Only present for channel messages; the ID of the channel.
subject:
type: string
description: |
The `topic` of the message. Currently always `""` for direct messages,
though this could change if Zulip adds support for topics in direct
message conversations.
The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
submessages:
type: array
description: |
Data used for certain experimental Zulip integrations.
items:
type: object
additionalProperties: false
properties:
msg_type:
type: string
description: |
The type of the message.
content:
type: string
description: |
The new content of the submessage.
message_id:
type: integer
description: |
The ID of the message to which the submessage has been added.
sender_id:
type: integer
description: |
The ID of the user who sent the message.
id:
type: integer
description: |
The ID of the submessage.
timestamp:
type: integer
description: |
The UNIX timestamp for when the message was sent,
in UTC seconds.
topic_links:
type: array
items:
type: object
additionalProperties: false
properties:
text:
type: string
description: |
The original link text present in the topic.
url:
type: string
description: |
The expanded target url which the link points to.
description: |
Data on any links to be included in the `topic`
line (these are generated by [custom linkification
filters](/help/add-a-custom-linkifier) that match content in the
message's topic.)
**Changes**: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1). Previously, this field was called
`subject_links`; clients are recommended to rename `subject_links` to `topic_links`
if present for compatibility with older Zulip servers.
type:
type: string
description: |
The type of the message: `"stream"` or `"private"`.
ModernPresenceFormat:
type: object
description: |
`{user_id}`: Presence data (modern format) for the user with
the specified ID.
additionalProperties: false
properties:
active_timestamp:
type: integer
description: |
The UNIX timestamp of the last time a client connected
to Zulip reported that the user was actually present
(e.g. via focusing a browser window or interacting
with a computer running the desktop app).
Clients should display users with a current
`active_timestamp` as fully present.
idle_timestamp:
type: integer
description: |
The UNIX timestamp of the last time the user had a
client connected to Zulip, including idle clients
where the user hasn't interacted with the system
recently.
The Zulip server has no way of distinguishing whether
an idle web app user is at their computer, but hasn't
interacted with the Zulip tab recently, or simply left
their desktop computer on when they left.
Thus, clients should display users with a current
`idle_timestamp` but no current `active_timestamp` as
potentially present.
LegacyPresenceFormat:
type: object
description: |
`{client_name}` or `"aggregated"`: Object containing the details of the user's
presence.
**Changes**: Starting with Zulip 7.0 (feature level 178), this will always
contain two keys, `"website"` and `"aggregated"`, with identical data. The
server no longer stores which client submitted presence updates.
Previously, the `{client_name}` keys for these objects were the names of the
different clients where the user was logged in, for example `website` or
`ZulipDesktop`.
additionalProperties: false
properties:
client:
type: string
description: |
The client's platform name.
**Changes**: Starting with Zulip 7.0 (feature level 178), this will
always be `"website"` as the server no longer stores which client
submitted presence data.
status:
type: string
enum:
- idle
- active
description: |
The status of the user on this client. Will be either `"idle"`
or `"active"`.
timestamp:
type: integer
description: |
The UNIX timestamp of when this client sent the user's presence
to the server with the precision of a second.
pushable:
type: boolean
description: |
Whether the client is capable of showing mobile/push notifications
to the user.
Not present in objects with the `"aggregated"` key.
**Changes**: Starting with Zulip 7.0 (feature level 178), always
`false` when present as the server no longer stores which client
submitted presence data.
UserStatus:
type: object
additionalProperties: false
properties:
away:
type: boolean
deprecated: true
description: |
If present, the user has marked themself "away".
**Changes**: Deprecated in Zulip 6.0 (feature level 148);
starting with that feature level, `away` is a legacy way to
access the user's `presence_enabled` setting, with
`away = !presence_enabled`. To be removed in a future release.
status_text:
type: string
description: |
If present, the text content of the user's status message.
emoji_name:
type: string
description: |
If present, the name for the emoji to associate with the user's status.
**Changes**: New in Zulip 5.0 (feature level 86).
emoji_code:
type: string
description: |
If present, a unique identifier, defining the specific emoji codepoint
requested, within the namespace of the `reaction_type`.
**Changes**: New in Zulip 5.0 (feature level 86).
reaction_type:
type: string
enum:
- unicode_emoji
- realm_emoji
- zulip_extra_emoji
description: |
If present, a string indicating the type of emoji. Each emoji
`reaction_type` has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86).
Draft:
type: object
description: |
A dictionary for representing a message draft.
properties:
id:
type: integer
description: |
The unique ID of the draft. It will only used whenever the drafts are
fetched. This field should not be specified when the draft is being
created or edited.
type:
type: string
description: |
The type of the draft. Either unaddressed (empty string), `"stream"`,
or `"private"` (for one-on-one and group direct messages).
enum:
- ""
- stream
- private
to:
type: array
description: |
An array of the tentative target audience IDs. For channel
messages, this should contain exactly 1 ID, the ID of the
target channel. For direct messages, this should be an array
of target user IDs. For unaddressed drafts, this is ignored,
and clients should send an empty array.
items:
type: integer
topic:
type: string
description: |
For channel message drafts, the tentative topic name. For direct
or unaddressed messages, this will be ignored and should ideally
be the empty string. Should not contain null bytes.
content:
type: string
description: |
The body of the draft. Should not contain null bytes.
timestamp:
type: integer
description: |
A Unix timestamp (seconds only) representing when the draft was
last edited. When creating a draft, this key need not be present
and it will be filled in automatically by the server.
example: 1595479019
additionalProperties: false
required:
- type
- to
- topic
- content
ScheduledMessage:
type: object
description: |
Object containing details of the scheduled message.
properties:
scheduled_message_id:
type: integer
description: |
The unique ID of the scheduled message, which can be used to
modify or delete the scheduled message.
This is different from the unique ID that the message will have
after it is sent.
type:
type: string
description: |
The type of the scheduled message. Either `"stream"` or `"private"`.
enum:
- stream
- private
to:
oneOf:
- type: integer
- type: array
items:
type: integer
description: |
The scheduled message's tentative target audience.
For channel messages, it will be the unique ID of the target
channel. For direct messages, it will be an array with the
target users' IDs.
topic:
type: string
description: |
Only present if `type` is `"stream"`.
The topic for the channel message.
content:
type: string
description: |
The content/body of the scheduled message, in text/markdown format.
rendered_content:
type: string
description: |
The content/body of the scheduled message rendered in HTML.
scheduled_delivery_timestamp:
type: integer
description: |
The UNIX timestamp for when the message will be sent
by the server, in UTC seconds.
example: 1595479019
failed:
type: boolean
description: |
Whether the server has tried to send the scheduled message
and it failed to successfully send.
Clients that support unscheduling and editing scheduled messages
should display scheduled messages with `"failed": true` with an
indicator that the server failed to send the message at the
scheduled time, so that the user is aware of the failure and can
get the content of the scheduled message.
**Changes**: New in Zulip 7.0 (feature level 181).
additionalProperties: false
required:
- scheduled_message_id
- type
- to
- content
- rendered_content
- scheduled_delivery_timestamp
- failed
GroupPermissionSetting:
description: |
Configuration for a group permission setting specifying the groups
to which the setting can be set to and the default values for the
setting.
additionalProperties: false
type: object
properties:
require_system_group:
type: boolean
description: |
Whether the setting can only be set to a system user group.
allow_internet_group:
type: boolean
description: |
Whether the setting can be set to `role:internet` system group.
allow_owners_group:
type: boolean
description: |
Whether the setting can be set to `role:owners` system group.
allow_nobody_group:
type: boolean
description: |
Whether the setting can be set to `role:nobody` system group.
allow_everyone_group:
type: boolean
description: |
Whether the setting can be set to `role:everyone` system group.
default_group_name:
type: string
description: |
Name of the default group for the setting.
id_field_name:
type: string
description: |
Name for the field used to pass the group ID for the setting.
default_for_system_groups:
type: string
nullable: true
description: |
Name of the default group for the setting for system groups.
This is non-null only for group-level settings.
allowed_system_groups:
type: array
description: |
An array of names of system groups to which the setting can
be set to.
If the list is empty, the setting can be set to system groups
based on the other boolean fields.
**Changes**: New in Zulip 8.0 (feature level 225).
items:
type: string
User:
allOf:
- $ref: "#/components/schemas/UserBase"
- additionalProperties: false
properties:
user_id: {}
delivery_email:
nullable: true
email: {}
full_name: {}
date_joined: {}
is_active: {}
is_owner: {}
is_admin: {}
is_guest: {}
is_billing_admin: {}
is_bot: {}
bot_type:
nullable: true
bot_owner_id:
nullable: true
role: {}
timezone: {}
avatar_url:
nullable: true
avatar_version: {}
profile_data: {}
UserBase:
type: object
description: |
A dictionary containing basic data on a given Zulip user.
properties:
user_id:
type: integer
description: |
The unique ID of the user.
delivery_email:
type: string
nullable: true
description: |
The user's real email address. This value will be `null` if you cannot
access user's real email address. For bot users, this field is always
set to the real email of the bot, because bot users always have
`email_address_visibility` set to everyone.
**Changes**: Prior to Zulip 7.0 (feature level 163), this field was
present only when `email_address_visibility` was restricted and you had
access to the user's real email. As of this feature level, this field
is always present, including the case when `email_address_visibility`
is set to everyone (and therefore not restricted).
email:
type: string
description: |
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
full_name:
type: string
description: |
Full name of the user or bot, used for all display purposes.
date_joined:
type: string
description: |
The time the user account was created.
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
is_owner:
type: boolean
description: |
A boolean specifying whether the user is an organization owner.
If true, `is_admin` will also be true.
**Changes**: New in Zulip 3.0 (feature level 8).
is_admin:
type: boolean
description: |
A boolean specifying whether the user is an organization administrator.
is_guest:
type: boolean
description: |
A boolean specifying whether the user is a guest user.
is_billing_admin:
type: boolean
description: |
A boolean specifying whether the user is a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
is_bot:
type: boolean
description: |
A boolean specifying whether the user is a bot or full account.
bot_type:
type: integer
nullable: true
description: |
An integer describing the type of bot:
- `null` if the user isn't a bot.
- `1` for a `Generic` bot.
- `2` for an `Incoming webhook` bot.
- `3` for an `Outgoing webhook` bot.
- `4` for an `Embedded` bot.
bot_owner_id:
type: integer
nullable: true
description: |
If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id`
is the user ID of the bot's owner (usually, whoever created the bot).
Will be `null` for legacy bots that do not have an owner.
**Changes**: New in Zulip 3.0 (feature level 1). In previous
versions, there was a `bot_owner` field containing the email
address of the bot's owner.
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: |
[Organization-level role](/api/roles-and-permissions) of the user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
**Changes**: New in Zulip 4.0 (feature level 59).
timezone:
type: string
description: |
The time zone of the user.
avatar_url:
type: string
nullable: true
description: |
URL for the user's avatar.
Will be `null` if the `client_gravatar`
query parameter was set to `true`, the current user has access to
this user's real email address, and this user's avatar is hosted by
the Gravatar provider (i.e. this user has never uploaded an avatar).
**Changes**: Before Zulip 7.0 (feature level 163), access to a
user's real email address was a realm-level setting. As of this
feature level, `email_address_visibility` is a user setting.
In Zulip 3.0 (feature level 18), if the client has the
`user_avatar_url_field_optional` capability, this will be missing at
the server's sole discretion.
avatar_version:
type: integer
description: |
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
profile_data:
$ref: "#/components/schemas/profile_data"
profile_data:
type: object
description: |
Only present if `is_bot` is false; bots can't have custom profile fields.
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single `value` key; for those custom profile fields
supporting Markdown, a `rendered_value` key will also be present.
additionalProperties:
type: object
additionalProperties: false
description: |
`{id}`: Object with data about what value the user filled in the custom
profile field with that ID.
properties:
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support Markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
JsonResponseBase:
type: object
properties:
result:
type: string
JsonSuccess:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example: {"msg": "", "result": "success"}
JsonSuccessBase:
description: |
**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`][ignored_params] array.
A typical successful JSON response may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
allOf:
- $ref: "#/components/schemas/JsonResponseBase"
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: "#/components/schemas/IgnoredParametersUnsupported"
IgnoredParametersSuccess:
allOf:
- $ref: "#/components/schemas/IgnoredParametersBase"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
description: |
**Changes**: The [`ignored_parameters_unsupported`][ignored_params]
array was added as a possible return value for all REST API endpoint
JSON success responses in Zulip 7.0 (feature level 167).
Previously, it was added to
[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings)
in Zulip 5.0 (feature level 111) and to
[`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults)
in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0
(feature level 78) as a return value for the
[`PATCH /settings`](/api/update-settings) endpoint.
A typical successful JSON response with ignored parameters may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
example:
{
"ignored_parameters_unsupported":
["invalid_param_1", "invalid_param_2"],
"msg": "",
"result": "success",
}
IgnoredParametersBase:
allOf:
- $ref: "#/components/schemas/JsonResponseBase"
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: "#/components/schemas/IgnoredParametersUnsupported"
ApiKeyResponse:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- required:
- api_key
- email
additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
api_key:
type: string
description: |
The API key that can be used to authenticate as the requested user.
email:
type: string
description: |
The email address of the user who owns the API key.
user_id:
type: integer
description: |
The unique ID of the user who owns the API key.
**Changes**: New in Zulip 7.0 (feature level 171).
example:
{
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
"email": "iago@zulip.com",
"msg": "",
"result": "success",
"user_id": 5,
}
CodedError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
CodedErrorBase:
allOf:
- $ref: "#/components/schemas/JsonResponseBase"
- required:
- result
- msg
- code
properties:
result:
enum:
- error
msg:
type: string
code:
type: string
description: |
A string that identifies the error.
BadEventQueueIdError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
queue_id:
type: string
description: |
The string that identifies the invalid event queue.
example:
{
"code": "BAD_EVENT_QUEUE_ID",
"msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8",
"queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8",
"result": "error",
}
InvalidMessageError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
example:
{
"msg": "Invalid message(s)",
"code": "BAD_REQUEST",
"result": "error",
}
InvalidChannelError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
example:
{
"msg": "Invalid channel ID",
"code": "BAD_REQUEST",
"result": "error",
}
NonExistingChannelNameError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream:
type: string
description: |
The name of the channel that could not be found.
example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Channel 'nonexistent' does not exist",
"result": "error",
"stream": "nonexistent",
}
NonExistingChannelIdError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream_id:
type: integer
description: |
The channel ID that could not be found.
example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Channel with ID '9' does not exist",
"result": "error",
"stream_id": 9,
}
InvalidApiKeyError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "INVALID_API_KEY",
"msg": "Invalid API key",
"result": "error",
}
description: |
### Invalid API key
A typical failed JSON response for when the API key is invalid.
InvitationFailedError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
errors:
type: array
items:
type: array
items:
oneOf:
- type: string
- type: boolean
description: |
An array of arrays of length 3, where each inner array consists of (a) an email
address that was skipped while sending invitations, (b) the corresponding error
message, and (c) a boolean which is `true` when the email address already uses Zulip
and the corresponding user is deactivated in the organization.
sent_invitations:
description: |
A boolean specifying whether any invitations were sent.
type: boolean
daily_limit_reached:
type: boolean
description: |
A boolean specifying whether the limit on the number of invitations that can
be sent in the organization in a day has been reached.
license_limit_reached:
type: boolean
description: |
A boolean specifying whether the organization have enough unused Zulip licenses
to invite specified number of users.
MissingArgumentError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
### Missing request parameter
A typical failed JSON response for when a required request parameter
is not supplied.
The value of `var_name` contains information about the missing parameter.
properties:
result: {}
msg: {}
code: {}
var_name:
type: string
description: |
It contains the information about the missing parameter.
example:
{
"code": "REQUEST_VARIABLE_MISSING",
"msg": "Missing 'content' argument",
"result": "error",
"var_name": "content",
}
IncompatibleParametersError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
### Incompatible request parameters
A typical failed JSON response for when two or more, optional
parameters are supplied that are incompatible with each other.
The value of `parameters` in the response is string containing
the parameters, separated by commas, that are incompatible.
properties:
result: {}
msg: {}
code: {}
parameters:
type: string
description: |
A string containing the parameters, separated by commas,
that are incompatible.
example:
{
"code": "BAD_REQUEST",
"msg": "Unsupported parameter combination: object_id, object_name",
"result": "error",
"parameters": "object_id, object_name",
}
UserNotAuthorizedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error",
}
description: |
### User not authorized for query
A typical failed JSON response for when the user is not authorized for
a query.
UserDeactivatedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "USER_DEACTIVATED",
"msg": "Account is deactivated",
"result": "error",
}
description: |
### User account deactivated
A typical failed json response for when user's account is deactivated.
**Changes**: As of Zulip 5.0 (feature level 76), these errors use the
HTTP 401 status code. Before this feature level, they used the HTTP 403
status code.
RateLimitedError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
### Rate limit exceeded
A typical failed JSON response for when a rate limit is exceeded.
Zulip sets a few [HTTP response headers][rate-limit-headers]
to help with preventing rate limit errors.
The value of `retry-after` in the response indicates how many
seconds the client must wait before making additional requests.
**Changes**: Before Zulip 4.0 (feature level 36), the `code` key
was not present in rate limit errors.
[rate-limit-headers]: /api/http-headers#rate-limiting-response-headers
properties:
result: {}
msg: {}
code: {}
retry-after:
type: integer
description: |
How many seconds the client must wait before making
additional requests.
example:
{
"code": "RATE_LIMIT_HIT",
"msg": "API usage exceeded rate limit",
"result": "error",
"retry-after": 28.706807374954224,
}
RealmDeactivatedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "REALM_DEACTIVATED",
"msg": "This organization is deactivated",
"result": "error",
}
description: |
### Realm deactivated
A typical failed json response for when user's organization is deactivated.
**Changes**: As of Zulip 5.0 (feature level 76), these errors use the
HTTP 401 status code. Before this feature level, they used the HTTP 403
status code.
InvalidPushDeviceTokenError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "INVALID_PUSH_DEVICE_TOKEN",
"msg": "Device not recognized",
"result": "error",
}
description: |
## Invalid push device token
A typical failed JSON response for when the push device token is not
recognized by the Zulip server:
InvalidRemotePushDeviceTokenError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "INVALID_REMOTE_PUSH_DEVICE_TOKEN",
"msg": "Device not recognized by the push bouncer",
"result": "error",
}
description: |
## Invalid push device token
A typical failed JSON response for when the push device token is not recognized
by the push notification bouncer:
Event_types:
description: |
A JSON-encoded array indicating which types of events you're interested
in. Values that you might find useful include:
- **message** (messages)
- **subscription** (changes in your subscriptions)
- **realm_user** (changes to users in the organization and
their properties, such as their name).
If you do not specify this parameter, you will receive all
events, and have to filter out the events not relevant to
your client in your client code. For most applications, one
is only interested in messages, so one specifies:
`"event_types": ["message"]`
Event types not supported by the server are ignored, in order to simplify
the implementation of client apps that support multiple server versions.
type: array
items:
type: string
example: ["message"]
Narrow:
description: |
A JSON-encoded array of arrays of length 2 indicating the
[narrow filter(s)](/api/construct-narrow) for which you'd
like to receive events for.
For example, to receive events for direct messages (including
group direct messages) received by the user, one can use
`"narrow": [["is", "dm"]]`.
Unlike the API for [fetching messages](/api/get-messages),
this narrow parameter is simply a filter on messages that the
user receives through their channel subscriptions (or because
they are a recipient of a direct message).
This means that a client that requests a `narrow` filter of
`[["channel", "Denmark"]]` will receive events for new messages
sent to that channel while the user is subscribed to that
channel. The client will not receive any message events at all
if the user is not subscribed to `"Denmark"`.
Newly created bot users are not usually subscribed to any
channels, so bots using this API need to be
[subscribed](/api/subscribe) to any channels whose messages
you'd like them to process using this endpoint.
See the `all_public_streams` parameter for how to process all
public channel messages in an organization.
**Changes**: See [changes section](/api/construct-narrow#changes)
of search/narrow filter documentation.
type: array
items:
type: array
items:
type: string
default: []
example: [["channel", "Denmark"]]
AllPublicChannels:
description: |
Whether you would like to request message events from all public
channels. Useful for workflow bots that you'd like to see all new messages
sent to public channels. (You can also subscribe the user to private channels).
type: boolean
default: false
example: true
RequiredContent:
description: |
The content of the message.
Clients should use the `max_message_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum message size.
type: string
example: Hello
OptionalContent:
description: |
The updated content of the target message.
Clients should use the `max_message_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum message size.
Note that a message's content and channel cannot be changed at the
same time, so sending both `content` and `stream_id` parameters will
throw an error.
type: string
example: Hello
ChannelPostPolicy:
description: |
[Policy][permission-level] for which users can post messages to the channel.
- 1 = Any user can post.
- 2 = Only administrators can post.
- 3 = Only [full members][calc-full-member] can post.
- 4 = Only moderators can post.
**Changes**: New in Zulip 3.0 (feature level 1), replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
type: integer
default: 1
example: 2
HistoryPublicToSubscribers:
description: |
Whether the channel's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the channel.
Corresponds to the [shared history](/help/channel-permissions)
option in documentation.
type: boolean
example: false
Principals:
description: |
A list of user IDs (preferred) or Zulip API email
addresses of the users to be subscribed to or unsubscribed
from the channels specified in the `subscriptions` parameter. If
not provided, then the requesting user/bot is subscribed.
**Changes**: The integer format is new in Zulip 3.0 (feature level 9).
oneOf:
- type: array
items:
type: string
- type: array
items:
type: integer
example: ["ZOE@zulip.com"]
ReactionType:
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
If an API client is adding/removing a vote on an existing reaction,
it should pass this parameter using the value the server provided
for the existing reaction for specificity. Supported values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: In Zulip 3.0 (feature level 2), this parameter became
optional for [custom emoji](/help/custom-emoji);
previously, this endpoint assumed `unicode_emoji` if this
parameter was not specified.
type: string
example: "unicode_emoji"
EmojiCode:
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
For most API clients, you won't need this, but it's important
for Zulip apps to handle rare corner cases when
adding/removing votes on an emoji reaction added previously by
another user.
If the existing reaction was added when the Zulip server was
using a previous version of the emoji data mapping between
Unicode codepoints and human-readable names, sending the
`emoji_code` in the data for the original reaction allows the
Zulip server to correctly interpret your upvote as an upvote
rather than a reaction with a "different" emoji.
type: string
example: "1f419"
MessageRetentionDays:
description: |
Number of days that messages sent to this channel will be stored
before being automatically deleted by the [message retention
policy](/help/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).
oneOf:
- type: string
- type: integer
example: "20"
CanRemoveSubscribersGroupId:
description: |
ID of the [user group](/api/get-user-groups) whose members are
allowed to unsubscribe others from the channel. Note that a user
who is a member of the specified user group must also [have
access](/help/channel-permissions) to the channel in order to
unsubscribe others.
This setting can currently only be set to user groups that are
system groups, except for the system groups named
`"role:internet"` and `"role:owners"`.
**Changes**: Before Zulip 8.0 (feature level 197),
the `can_remove_subscribers_group` setting
was named `can_remove_subscribers_group_id`.
New in Zulip 7.0 (feature level 161).
type: integer
example: 20
LinkifierPattern:
description: |
The [Python regular
expression](https://docs.python.org/3/howto/regex.html) that should
trigger the linkifier.
type: string
example: "#(?P<id>[0-9]+)"
LinkifierURLTemplate:
description: |
The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
compliant URL template used for the link.
If you used named groups in `pattern`, you can insert their
content here with `{name_of_group}`.
**Changes**: New in Zulip 7.0 (feature level 176). This replaced
the `url_format_string` parameter, which was a format string in which
named groups' content could be inserted with `%(name_of_group)s`.
type: string
example: https://github.com/zulip/zulip/issues/{id}
###################
# Shared responses
###################
responses:
SimpleSuccess:
description: Success.
content:
application/json:
schema:
$ref: "#/components/schemas/JsonSuccess"
SuccessIgnoredParameters:
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/IgnoredParametersSuccess"
####################
# Shared parameters
####################
parameters:
UserGroupId:
name: user_group_id
in: path
description: |
The ID of the target user group.
schema:
type: integer
example: 33
required: true
QueueId:
name: queue_id
in: query
description: |
The ID of an event queue that was previously registered via
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
schema:
type: string
example: fb67bf8a-c031-47cc-84cf-ed80accacda8
required: true
ChannelIdInPath:
name: stream_id
in: path
description: |
The ID of the channel to access.
schema:
type: integer
example: 1
required: true
ClientGravatar:
name: client_gravatar
in: query
description: |
Whether the client supports computing gravatars URLs. If
enabled, `avatar_url` will be included in the response only
if there is a Zulip avatar, and will be `null` for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The `client_gravatar` field is set to `true` if
clients can compute their own gravatars.
**Changes**: The default value of this parameter was `false`
prior to Zulip 5.0 (feature level 92).
schema:
type: boolean
default: true
example: false
MessageId:
name: message_id
in: path
description: |
The target message's ID.
schema:
type: integer
example: 43
required: true
UserId:
name: user_id
in: path
description: |
The target user's ID.
schema:
type: integer
example: 12
required: true
MutedUserId:
name: muted_user_id
in: path
description: |
The ID of the user to mute/unmute.
**Changes**: Before Zulip 8.0 (feature level 188), bot users could not
be muted/unmuted, and specifying a bot user's ID returned an error response.
schema:
type: integer
example: 10
required: true
IncludeSubscribers:
name: include_subscribers
in: query
description: |
Whether each returned channel object should include a `subscribers`
field containing a list of the user IDs of its subscribers.
(This may be significantly slower in organizations with
thousands of users subscribed to many channels.)
**Changes**: New in Zulip 2.1.0.
schema:
type: boolean
default: false
example: true
IncludeCustomProfileFields:
name: include_custom_profile_fields
in: query
description: |
Whether the client wants [custom profile field](/help/custom-profile-fields)
data to be included in the response.
**Changes**: New in Zulip 2.1.0. Previous versions do not offer these
data via the API.
schema:
type: boolean
default: false
example: true
DirectMemberOnly:
name: direct_member_only
in: query
description: |
Whether to consider only the direct members of user group and not members
of its subgroups. Default is `false`.
schema:
type: boolean
example: false
required: false
Reference in New Issue View Git Blame Copy Permalink