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

20805 lines
964 KiB
YAML
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"
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).
parameters:
- name: username
in: query
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.
schema:
type: string
example: iago@zulip.com
required: true
- name: password
in: query
schema:
type: string
example: abcd1234
description: |
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
required: true
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.
parameters:
- name: username
in: query
description: |
The email address for the user that owns the API key.
schema:
type: string
example: iago@zulip.com
required: true
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 stream 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 streams.
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
**Changes**: 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",
"stream_id": 9,
"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 streams.
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 streams.
items:
type: object
additionalProperties: false
description: |
Dictionary containing details about the unsubscribed stream.
properties:
stream_id:
type: integer
description: |
The ID of the stream.
name:
type: string
description: |
The name of the stream.
additionalProperties: false
example:
{
"type": "subscription",
"op": "remove",
"subscriptions":
[{"name": "test_stream", "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 stream has been updated. This event is used
only for personal properties like `is_muted` or `pin_to_top`.
See the [stream update event](/api/get-events#stream-update)
for updates to global properties of a stream.
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 stream 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 stream, or their
subscription is newly visible to the current user.
When a user subscribes to a stream, the current user will receive this
event only if they [have permission to see the stream's subscriber
list](/help/stream-permissions). When the current user gains permission
to see a given stream's subscriber list, they will receive this event
for the existing subscriptions to the stream.
**Changes**: Prior to Zulip 8.0 (feature level 220), this event was
incorrectly not sent to guest users when subscribers to web-public
streams and subscribed public streams changed.
Prior to Zulip 8.0 (feature level 205), this event was not sent when
a user gained access to a stream 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 stream 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 stream 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 streams 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 streams.
**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 streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream 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
streams and subscribed public streams 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 stream 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 streams 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 interacting with older servers should treat this field as an old name
for `stream_wildcard_mentioned`. @topic 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.
**Changes**: 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**: Prior to Zulip 8.0 (feature level 228), this event was deprecated.
**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
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 stream is created to users who can see
the new stream exists (for private streams, only subscribers and
organization administrators will receive this event).
This event is also sent when a user gains access to a stream they
previously [could not access](/help/stream-permissions), such as
when their [role](/help/roles-and-permissions) changes, a
private stream is made public, or a guest user is subscribed
to a public (or private) stream.
Note that organization administrators who are not subscribed will
not be able to see content on the stream; 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 stream was created.
Prior to Zulip 8.0 (feature level 205), this event was not sent
when a user gained access to a stream 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 stream by being
subscribed.
Prior to Zulip 6.0 (feature level 134), this event was not sent
when a private stream 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 stream objects, each containing
details about the newly added stream(s).
items:
$ref: "#/components/schemas/BasicStream"
additionalProperties: false
example:
{
"type": "stream",
"op": "create",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"date_created": 1691057093,
"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 stream when it is deactivated.
This event is also sent when a user loses access to a stream they
previously [could access](/help/stream-permissions) because they
are unsubscribed from a private stream 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 stream 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 stream objects, each containing
details about a stream that was deleted.
items:
$ref: "#/components/schemas/BasicStream"
additionalProperties: false
example:
{
"type": "stream",
"op": "delete",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"date_created": 1691057093,
"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 stream exists
when a property of that stream changes.
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 stream whose details have changed.
name:
type: string
description: |
The name of the stream whose details have changed.
property:
type: string
description: |
The property of the stream which has changed. See
[/stream GET](/api/get-streams) for details on the various
properties of a stream.
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 stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
history_public_to_subscribers:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. `"invite_only": false` implies
`"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future.
is_web_public:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
Whether the stream'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_stream",
"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,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
},
{
"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,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
"display_in_profile_summary": true,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
},
],
"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 stream groups.
Default stream 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 stream group.
items:
$ref: "#/components/schemas/DefaultStreamGroup"
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,
"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,
"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,
"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 streams 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 stream.
items:
$ref: "#/components/schemas/DefaultStream"
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,
"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 received the message.
This event is also sent when the user loses access to a message,
such as when it is [moved to a stream][message-move-stream] that
the user does not [have permission to access][stream-access].
**Changes**: Before Zulip 5.0 (feature level 77), events
for direct messages contained additional `sender_id` and
`recipient_id` fields.
[message-move-stream]: /help/move-content-to-another-stream
[stream-access]: /help/stream-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 stream 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 stream 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.
**Changes**: 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 stream 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 have 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 was named
as `Hotspots`. One-time notice wasn't available earlier.
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 as `hotspots`. One-time notice wasn't available earlier.
items:
$ref: "#/components/schemas/OnboardingStep"
example:
{
"type": "onboarding_steps",
"onboarding_steps":
[
{
"type": "hotspot",
"name": "intro_streams",
"title": "Catch up on a stream",
"description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
"delay": 0.5,
"has_trigger": false,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a message's content, topic and/or
stream 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 stream 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 stream or topic changes
encoded in this event should be applied.
These messages are guaranteed to have all been previously sent
to stream `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 stream 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 interacting with older servers should treat this field as an old name
for `stream_wildcard_mentioned`. @topic 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 stream.
The name of the stream 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 stream.
The pre-edit stream 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 stream message. Previously, it
was not present when only the content of the stream message was
edited.
new_stream_id:
type: integer
description: |
Only present if message(s) were moved to a different stream.
The post-edit stream 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 stream.
The choice the editing user made about which messages should be
affected by a stream/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 stream.
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.
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.
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 stream 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 stream 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 stream 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 stream 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 stream 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 stream 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 stream 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 stream 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 stream,
or messages are moved to a not-subscribed stream, 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 stream 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.
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 stream 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:
type: integer
description: |
ID of the new user group whose members are allowed to mention the
group.
**Changes**: Before Zulip 8.0 (feature level 198),
the `can_mention_group` setting
was named `can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups
could be mentioned if and only if they were not system groups.
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 [data export](/help/export-your-organization)
when the status of the 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
data about a single organization export request.
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 can use this event to know when they should get a new
event queue after a server upgrade. Clients doing so must implement
a random delay strategy to spread such restarts over 10 minutes or
more to avoid creating a synchronized thundering herd effect.
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 can safely avoid refetching their state and
creating a new event queue when the API feature level has not
changed, or when they know the specific feature level change
is not relevant to the client (E.g. it just adds a new endpoint
that the client doesn't use).
**Changes**: New in Zulip 4.0 (feature level 59).
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.
server_generation:
type: integer
description: |
The timestamp at which the server started.
additionalProperties: false
example:
{
"id": 0,
"immediate": true,
"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
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:
description: |
Boolean describing whether the authentication method (i.e. its key)
is enabled in this organization.
type: boolean
description: |
Dictionary of authentication method keys with boolean values that
describe whether the named authentication method is enabled for 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).
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).
create_public_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create public streams in this organization.
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `create_stream_policy` setting.
create_private_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create private streams in this organization.
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `create_stream_policy` setting.
create_web_public_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create web public streams in this organization.
**Changes**: New in Zulip 5.0 (feature level 103).
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.
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 streams 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 `create_web_public_stream_policy` 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/allow-image-link-previews).
inline_url_embed_preview:
type: boolean
description: |
Whether this organization has been configured to enable
[previews of linked websites](/help/allow-image-link-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 streams 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
stream 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
streams 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 streams 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 stream 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).
notifications_stream_id:
type: integer
description: |
The ID of the stream to which automated messages announcing the
[creation of new streams][new-stream-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-stream-announce]: /help/configure-notification-bot#new-stream-announcements
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.
private_message_policy:
type: integer
description: |
[Policy](/api/roles-and-permissions#permission-levels)
for [who can send direct messages](/help/restrict-direct-messages)
in this organization.
- 1 = Everyone
- 2 = Nobody
**Changes**: New in Zulip 3.0 (feature level 1).
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_notifications_stream_id:
type: integer
description: |
The ID of the stream 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-notification-bot#new-user-announcements
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 streams.
- 1 = Any user can use wildcard mentions in large streams.
- 2 = Only members can use wildcard mentions in large streams.
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large streams.
- 5 = Only organization administrators can use wildcard mentions in large streams.
- 6 = Nobody can use wildcard mentions in large streams.
- 7 = Only organization administrators and moderators can use wildcard mentions in large streams.
All users will receive a warning/reminder when using
mentions in large streams, 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). Stream 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.
parameters:
- $ref: "#/components/parameters/QueueId"
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 stream ID
tags: ["streams"]
description: |
Get the unique ID of a given stream.
parameters:
- name: stream
in: query
description: |
The name of the stream 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 stream.
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 stream name 'nonexistent'",
"result": "error",
}
description: |
An example JSON response for when the supplied stream 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 stream as read
tags: ["messages"]
description: |
Mark all the unread messages in a stream 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.
parameters:
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 43
required: true
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.
parameters:
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 43
required: true
- name: topic_name
in: query
description: |
The name of the topic whose messages should be marked as read.
schema:
type: string
example: new coffee machine
required: true
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.
parameters:
- name: drafts
in: query
description: |
A JSON-encoded list of containing new draft objects.
content:
application/json:
schema:
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,
},
]
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 stream does not specify
exactly one stream ID:
example:
{
"code": "BAD_REQUEST",
"msg": "Must specify exactly 1 stream ID for stream 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
- name: draft
in: query
content:
application/json:
schema:
$ref: "#/components/schemas/Draft"
example:
{
"type": "stream",
"to": [1],
"topic": "questions",
"content": "how tough is a Lamy Safari?",
"timestamp": 1595479019,
}
description: |
A JSON-encoded object containing a replacement draft object for this ID.
required: true
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).
parameters:
- name: type
in: query
description: |
The type of scheduled message to be sent. `"direct"` for a direct
message and `"stream"` for a stream message.
In Zulip 7.0 (feature level 174), `"direct"` was added as the
preferred way to indicate the type of a direct message, deprecating
the original `"private"`. While `"private"` is supported for
scheduling direct messages, clients are encouraged to use to the
modern convention because support for `"private"` may eventually
be removed.
schema:
type: string
enum:
- direct
- stream
- private
example: direct
required: true
- name: to
in: query
description: |
The scheduled message's tentative target audience.
For stream messages, the integer ID of the stream.
For direct messages, a list containing integer user IDs.
content:
application/json:
schema:
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example: [9, 10]
required: true
- $ref: "#/components/parameters/RequiredContent"
- name: topic
in: query
description: |
The topic of the message. Only required for stream messages
(`"type": "stream"`), ignored otherwise.
Clients should use the `max_topic_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum topic length.
schema:
type: string
example: Castle
allowEmptyValue: true
- name: scheduled_delivery_timestamp
in: query
schema:
type: integer
description: |
The UNIX timestamp for when the message will be sent,
in UTC seconds.
required: true
example: 3165826990
- name: read_by_sender
in: query
schema:
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
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/NonExistingStreamIdError"
- description: |
A typical failed JSON response for when a stream message is scheduled
to be sent to a stream 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
- name: type
in: query
description: |
The type of scheduled message to be sent. `"direct"` for a direct
message and `"stream"` for a stream 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"`, then the `topic` parameter is also required.
In Zulip 7.0 (feature level 174), `"direct"` was added as the
preferred way to indicate the type of a direct message, deprecating
the original `"private"`. While `"private"` is supported for
scheduling direct messages, clients are encouraged to use to the
modern convention because support for `"private"` may eventually
be removed.
schema:
type: string
enum:
- direct
- stream
- private
example: stream
- name: to
in: query
description: |
The scheduled message's tentative target audience.
For stream messages, the integer ID of the stream.
For direct messages, a list containing integer user IDs.
Required when updating the `type` of the scheduled message.
content:
application/json:
schema:
oneOf:
- type: integer
- type: array
items:
type: integer
minLength: 1
example: 8
- name: content
in: query
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.
schema:
type: string
example: Hello
- name: topic
in: query
description: |
The updated topic of the scheduled message.
Required when updating the `type` of the scheduled message to
`"stream"`. 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.
schema:
type: string
example: Castle
- name: scheduled_delivery_timestamp
in: query
schema:
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
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/NonExistingStreamIdError"
- description: |
A typical failed JSON response for when a stream message is scheduled
to be sent to a stream 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: ["streams"]
summary: Add a default stream
x-requires-administrator: true
description: |
Add a stream to the set of [default streams][default-streams]
for new users joining the organization.
[default-streams]: /help/set-default-streams-for-new-users
parameters:
- name: stream_id
in: query
description: |
The ID of the target stream.
schema:
type: integer
example: 7
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
A typical failed JSON response for when an invalid stream ID is passed:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Private streams cannot be made default.",
"result": "error",
}
description: |
A typical failed JSON response for when a user tries to add a private stream
to the default streams set:
delete:
operationId: remove-default-stream
summary: Remove a default stream
tags: ["streams"]
description: |
Remove a stream from the set of [default streams][default-streams]
for new users joining the organization.
[default-streams]: /help/set-default-streams-for-new-users
x-requires-administrator: true
parameters:
- name: stream_id
in: query
description: |
The ID of the target stream.
schema:
type: integer
example: 7
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
A typical failed JSON response for when an invalid stream 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
streams before they [subscribe](/api/subscribe), and newly created
bot users are not usually subscribed to any streams.
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 `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 streams instead
of only the user's message history, then a specific narrow for
messages sent to all public streams can be used:
`{"operator": "streams", "operand": "public"}`.
Newly created bot users are not usually subscribed to any
streams, so bots using this API should either be
subscribed to appropriate streams or use a shared history
search narrow with this endpoint.
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
for three new filters related to direct messages: `is:dm`, `dm` and
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
`group-pm-with` respectively.
In Zulip 2.1.0, added support for using user/stream IDs when
constructing narrows for a message's sender, its stream and/or
its recipient(s).
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": "stream"}]
- $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 interacting with older servers should treat this field as an old name
for `stream_wildcard_mentioned`. @topic 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 [stream message](/help/streams-and-topics) or a
[direct message](/help/direct-messages).
parameters:
- name: type
in: query
description: |
The type of message to be sent.
`"direct"` for a direct message and `"stream"` for a stream message.
**Changes**: 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.
schema:
type: string
enum:
- direct
- stream
- private
example: direct
required: true
- name: to
in: query
description: |
For stream messages, either the name or integer ID of the stream. For
direct messages, either a list containing integer user IDs or a list
containing string Zulip API email addresses.
**Changes**: Support for using user/stream IDs was added in Zulip 2.0.0.
content:
application/json:
schema:
oneOf:
- type: string
- type: integer
- type: array
items:
type: string
- type: array
items:
type: integer
minLength: 1
example: [9, 10]
required: true
- $ref: "#/components/parameters/RequiredContent"
- name: topic
in: query
description: |
The topic of the message. Only required for stream messages
(`"type": "stream"`), 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.
schema:
type: string
example: Castle
- name: queue_id
in: query
schema:
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"
- name: local_id
in: query
schema:
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"
- name: read_by_sender
in: query
schema:
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
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 stream. 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/NonExistingStreamNameError"
- description: |
A typical failed JSON response for when a stream message is sent to a stream
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 stream wildcard mentions in this stream.",
"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 stream.
**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 stream
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 stream was edited.
The ID of the stream 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 stream was edited.
The ID of the stream 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>wildcard_mentioned</code></td>
<td>
Whether this message contained either a
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-stream">stream wildcard mention</a>
like @**all** or a topic wildcard mention (@**topic**). Cannot be changed
by the user directly, but can change if the message is edited to add/remove
a stream or/and topic wildcard mention.
**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 interacting with older servers should treat this field as an old name
for `stream_wildcard_mentioned`. @topic mentions were not available prior to
this feature level.
</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-stream">stream wildcard mention</a>
like @**all**. Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a stream wildcard mention.
**Changes**: New in Zulip 8.0 (feature level 224).
</td>
</tr>
<tr>
<td><code>topic_wildcard_mentioned</code></td>
<td>
Whether this message contained a topic wildcard mention (@**topic**).
Cannot be changed by the user directly, but can change if
the message is edited to add/remove a topic wildcard mention.
**Changes**: 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 `true` 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 stream
before they subscribed to that stream). Cannot be
changed by the user directly.
</td>
</tr>
</tbody>
</table>
</div>
parameters:
- name: messages
in: query
description: |
An array containing the IDs of the target messages.
content:
application/json:
schema:
type: array
items:
type: integer
example: [4, 8, 15]
required: true
- name: op
in: query
description: |
Whether to `add` the flag or `remove` it.
schema:
type: string
enum:
- add
- remove
example: add
required: true
- name: flag
in: query
description: |
The flag that should be added/removed.
schema:
type: string
example: read
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: 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
parameters:
- name: anchor
in: query
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.
schema:
$ref: "#/components/schemas/Anchor"
example: "43"
required: true
- name: include_anchor
in: query
description: |
Whether a message with the specified ID matching the narrow
should be included in the update range.
schema:
type: boolean
default: true
example: false
- name: num_before
in: query
description: |
Limit the number of messages preceding the anchor in the
update range. The server may decrease this to bound
transaction sizes.
schema:
type: integer
minimum: 0
example: 4
required: true
- name: num_after
in: query
description: |
Limit the number of messages following the anchor in the
update range. The server may decrease this to bound
transaction sizes.
schema:
type: integer
minimum: 0
example: 8
required: true
- name: narrow
in: query
description: |
The narrow you want update flags within. See how to
[construct a narrow](/api/construct-narrow).
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
for three new filters related to direct messages: `is:dm`, `dm` and
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
`group-pm-with` respectively.
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": "stream"}]
required: true
- name: op
in: query
description: |
Whether to `add` the flag or `remove` it.
schema:
type: string
enum:
- add
- remove
example: add
required: true
- name: flag
in: query
description: |
The flag that should be added/removed. See [available
flags](/api/update-message-flags#available-flags).
schema:
type: string
example: read
required: true
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 message
tags: ["messages"]
description: |
Render a message to HTML.
parameters:
- $ref: "#/components/parameters/RequiredContent"
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"
- name: emoji_name
in: query
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.
schema:
type: string
example: "octopus"
required: true
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/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 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"
- name: emoji_name
in: query
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.
schema:
type: string
example: "octopus"
required: false
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/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 the list of IDs of users who have read a message.
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**: In Zulip 7.0 (feature level 177), narrows gained support
for three new filters related to direct messages: `is:dm`, `dm` and
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
`group-pm-with` respectively.
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 interacting with older servers should treat this field as an old name
for `stream_wildcard_mentioned`. @topic 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 stream 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 stream.
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 stream 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
stream 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 streams was
added, controlled by the realm setting
`move_messages_between_streams_limit_seconds`. Previously, all users who
had permission to move messages between streams did not have any time limit
restrictions when doing so.
Before Zulip 7.0 (feature level 159), editing streams 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"
- name: topic
in: query
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 stream message.
**Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
schema:
type: string
example: Castle
- name: propagate_mode
in: query
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 stream/topic.
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
- name: send_notification_to_old_thread
in: query
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 stream was changed.
New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: false
example: true
- name: send_notification_to_new_thread
in: query
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 stream was changed.
New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: true
example: true
- $ref: "#/components/parameters/OptionalContent"
- name: stream_id
in: query
description: |
The stream ID to move the message(s) to, to request moving
messages to another stream.
Should only be sent when changing the stream, and will throw an error
if the target message is not a stream message.
Note that a message's content and stream 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).
schema:
type: integer
example: 43
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 stream with [protected history](/help/stream-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
stream 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 stream wildcard mentions in this stream.",
"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 stream.
**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 URI.
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
description: |
The URI of the uploaded file.
example:
{
"msg": "",
"result": "success",
"uri": "/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**: This endpoint is limited to organization administrators
who additionally have the `can_create_users` permission for the Zulip
organization. Zulip Cloud users can request the `can_create_users`
permission for a bot 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
parameters:
- name: email
in: query
description: |
The email address of the new user.
schema:
type: string
example: username@example.com
required: true
- name: password
in: query
description: |
The password of the new user.
schema:
type: string
example: abcd1234
required: true
- name: full_name
in: query
description: |
The full name of the new user.
schema:
type: string
example: New User
required: true
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_or_email}/presence:
get:
operationId: get-user-presence
summary: Get user 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
organzation.
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
parameters:
- name: alert_words
in: query
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.
content:
application/json:
schema:
type: array
items:
type: string
example: ["foo", "bar"]
required: true
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
parameters:
- name: alert_words
in: query
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.
content:
application/json:
schema:
type: array
items:
type: string
example: ["foo"]
required: true
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/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.
parameters:
- name: status_text
schema:
type: string
allowEmptyValue: true
in: query
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
required: false
- name: away
deprecated: true
schema:
type: boolean
in: query
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
required: false
- name: emoji_name
schema:
type: string
allowEmptyValue: true
in: query
description: |
The name for the emoji to associate with this status.
**Changes**: New in Zulip 5.0 (feature level 86).
example: car
required: false
- name: emoji_code
schema:
type: string
in: query
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
required: false
- name: reaction_type
schema:
type: string
in: query
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
required: false
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 stream
tags: ["streams"]
description: |
Get all topics the user has access to in a specific stream.
Note that for private streams with [protected
history](/help/stream-permissions), the user will only have access to
topics of messages sent after they [subscribed to](/api/subscribe) the
stream. Similarly, a user's [bot](/help/bots-and-integrations#bot-type)
will only have access to messages sent after the bot was subscribed to
the stream, instead of when the user subscribed.
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
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 `topic` objects.
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/InvalidStreamError"
- description: |
An example JSON response for when the user is attempting to fetch the topics
of a non-existing stream (or also a private stream they don't have access to):
/users/me/subscriptions:
get:
operationId: get-subscriptions
summary: Get subscribed streams
tags: ["streams"]
description: |
Get all streams 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 streams.
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
**Changes**: 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",
"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",
"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 stream
tags: ["streams"]
description: |
Subscribe one or more users to one or more streams.
If any of the specified streams do not exist, they are automatically
created. The initial [stream 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
stream depends on the [stream's privacy settings](/help/stream-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 stream, you may pass in
the `principals` parameter, like so:
parameters:
enum:
- subscriptions
- principals
parameters:
- name: subscriptions
in: query
description: |
A list of dictionaries containing the key `name` and value
specifying the name of the stream to subscribe. If the stream does not
exist a new stream is created. The description of the stream created can
be specified by setting the dictionary key `description` with an
appropriate value.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the stream.
Clients should use the `max_stream_name_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum stream name length.
description:
type: string
description: |
The [description](/help/change-the-stream-description)
to use for a new stream 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 stream description length.
required:
- name
example:
no-description:
value: {"name": "Verona"}
with-description:
value: {"name": "Verona", "description": "Italian city"}
example: [{"name": "Verona", "description": "Italian city"}]
required: true
- $ref: "#/components/parameters/Principals"
- name: authorization_errors_fatal
in: query
description: |
A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private stream) 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 streams
where the request encountered an authorization error will be listed
in the `unauthorized` key.
schema:
type: boolean
default: true
example: false
- name: announce
in: query
description: |
If one of the streams specified did not exist previously and is thus created
by this call, this determines whether [notification bot](/help/configure-notification-bot)
will send an announcement about the new stream's creation.
schema:
type: boolean
default: false
example: true
- name: invite_only
in: query
description: |
As described above, this endpoint will create a new stream if passed
a stream name that doesn't already exist. This parameters and the ones
that follow are used to request an initial configuration of a created
stream; they are ignored for streams that already exist.
This parameter determines whether any newly created streams will be
private streams.
schema:
type: boolean
default: false
example: true
- name: is_web_public
in: query
description: |
This parameter determines whether any newly created streams will be
web-public streams.
Note that creating web-public streams 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
`create_web_public_stream_policy` realm setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 98).
schema:
type: boolean
default: false
example: true
- name: is_default_stream
in: query
description: |
This parameter determines whether any newly created streams will be
added as [default streams][default-streams] for new users joining
the organization.
[default-streams]: /help/set-default-streams-for-new-users
**Changes**: New in Zulip 8.0 (feature level 200). Previously, default stream status
could only be changed using the [dedicated API endpoint](/api/add-default-stream).
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/MessageRetentionDays"
- $ref: "#/components/parameters/CanRemoveSubscribersGroupId"
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 streams that were subscribed
to as a result of the query.
additionalProperties:
description: |
`{email_address}`: List of the names of the streams 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 streams that the user/bot is
already subscribed to.
additionalProperties:
description: |
`{email_address}`: List of the names of the streams that the user is
already subscribed to.
type: array
items:
type: string
unauthorized:
type: array
items:
type: string
description: |
A list of names of streams that the requesting user/bot was not
authorized to subscribe to. Only present if `"authorization_errors_fatal": false`.
example:
{
"already_subscribed":
{"iago@zulip.com": ["new stream"]},
"msg": "",
"result": "success",
"subscribed": {"newbie@zulip.com": ["new stream"]},
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error",
"code": "BAD_REQUEST",
}
description: |
An example JSON response for when the requesting user does not have
access to a private stream and `"authorization_errors_fatal": true`:
patch:
operationId: update-subscriptions
summary: Update subscriptions
tags: ["streams"]
description: |
Update which streams you are subscribed to.
parameters:
- name: delete
in: query
description: |
A list of stream names to unsubscribe from.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Verona", "Denmark"]
required: false
- name: add
in: query
description: |
A list of objects describing which streams to subscribe to, optionally
including per-user subscription parameters (e.g. color) and if the
stream is to be created, its description.
content:
application/json:
schema:
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",
},
]
required: false
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 streams that were
subscribed to as a result of the query.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams 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 streams that the
user/bot is already subscribed to.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams 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 streams 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 streams which were unsubscribed
from as a result of the query.
example:
{
"msg": "",
"subscribed": {},
"already_subscribed": {"iago@zulip.com": ["Verona"]},
"not_removed": [],
"removed": ["new stream"],
"result": "success",
}
delete:
operationId: unsubscribe
summary: Unsubscribe from a stream
tags: ["streams"]
description: |
Unsubscribe yourself or other users from one or more streams.
In addition to managing the current user's subscriptions, this
endpoint can be used to remove other users from streams. This
is possible in 3 situations:
- Organization administrators can remove any user from any
stream.
- Users can remove a bot that they own from any stream that
the user [can access](/help/stream-permissions).
- Users can unsubscribe any user from a stream if they [have
access](/help/stream-permissions) to the stream and are a
member of the [user group](/api/get-user-groups) specified
by the [`can_remove_subscribers_group`][can-remove-parameter]
for the stream.
**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 streams 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 stream requires
administrative privileges.
parameters:
enum:
- subscriptions
- type: exclude
parameters:
enum:
- ""
description: |
You may specify the `principals` parameter like so:
parameters:
- name: subscriptions
in: query
description: |
A list of stream names to unsubscribe from. This parameter is called
`streams` in our Python API.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Verona", "Denmark"]
required: true
- $ref: "#/components/parameters/Principals"
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 streams 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 streams which were unsubscribed from as a result
of the query.
example:
{
"msg": "",
"not_removed": [],
"removed": ["new stream"],
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/NonExistingStreamNameError"
- description: |
A typical failed JSON response for when the target stream does not exist:
/users/me/subscriptions/muted_topics:
patch:
deprecated: true
operationId: mute-topic
summary: Topic muting
tags: ["streams"]
description: |
[Mute or unmute a topic](/help/mute-a-topic) within a stream 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
parameters:
- name: stream_id
in: query
description: |
The ID of the stream 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.
schema:
type: integer
example: 43
required: false
- name: stream
in: query
description: |
The name of the stream 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.
schema:
type: string
example: Denmark
required: false
- name: topic
in: query
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.
schema:
type: string
example: dinner
required: true
- name: op
in: query
description: |
Whether to mute (`add`) or unmute (`remove`) the provided topic.
schema:
type: string
enum:
- add
- remove
example: add
required: true
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).
parameters:
- name: token
in: query
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.
schema:
type: string
example: "111222"
required: false
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: ["streams"]
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
stream 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.
parameters:
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 1
required: true
- name: topic
in: query
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.
schema:
type: string
example: dinner
required: true
- name: visibility_policy
in: query
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 stream.
- 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted stream.
- 3 = Followed. [Follows the topic](/help/follow-a-topic).
In an unmuted stream, 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.
schema:
type: integer
enum:
- 0
- 1
- 2
example: 1
required: true
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.
- Stream 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 stream or realm", e.g. for organization
administration or showing stream 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/{user_id}/subscriptions/{stream_id}:
get:
operationId: get-subscription-status
summary: Get subscription status
tags: ["streams"]
description: |
Check whether a user is subscribed to a stream.
**Changes**: New in Zulip 3.0 (feature level 12).
parameters:
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/StreamIdInPath"
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 stream.
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 stream 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/Presence"
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,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
},
{
"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,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
"display_in_profile_summary": true,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
},
{
"id": 9,
"name": "Pronouns",
"type": 8,
"hint": "What pronouns should people use to refer to you?",
"order": 9,
},
],
}
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
parameters:
- name: order
in: query
description: |
A list of the IDs of all the custom profile fields defined in this
organization, in the desired new order.
content:
application/json:
schema:
type: array
items:
type: integer
example: [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
required: true
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
parameters:
- name: name
in: query
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.
schema:
type: string
example: "Favorite programming language"
- name: hint
in: query
description: |
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
schema:
type: string
example: "Your favorite programming language."
- name: field_type
in: query
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).
schema:
type: integer
example: 3
required: true
- name: field_data
in: query
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.
content:
application/json:
schema:
type: object
example:
{
"python": {"text": "Python", "order": "1"},
"java": {"text": "Java", "order": "2"},
}
- name: display_in_profile_summary
in: query
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).
schema:
type: boolean
example: true
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
parameters:
- name: dense_mode
in: query
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
schema:
type: boolean
example: true
- name: starred_message_counts
in: query
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
schema:
type: boolean
example: true
- name: fluid_layout_width
in: query
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.
schema:
type: boolean
example: true
- name: high_contrast_mode
in: query
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
schema:
type: boolean
example: true
- name: web_mark_read_on_scroll_policy
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: color_scheme
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: enable_drafts_synchronization
in: query
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.
schema:
type: boolean
example: true
- name: translate_emoticons
in: query
description: |
Whether to [translate emoticons to emoji](/help/configure-emoticon-translations)
in messages the user sends.
schema:
type: boolean
example: true
- name: display_emoji_reaction_users
in: query
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).
schema:
type: boolean
example: false
- name: web_home_view
in: query
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" - All messages 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).
schema:
type: string
example: all_messages
- name: web_escape_navigates_to_home_view
in: query
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).
schema:
type: boolean
example: true
- name: left_side_userlist
in: query
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
schema:
type: boolean
example: true
- name: emojiset
in: query
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
schema:
type: string
example: "google"
- name: demote_inactive_streams
in: query
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: user_list_style
in: query
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).
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: web_stream_unreads_count_display_policy
in: query
description: |
Configuration for which streams should be displayed with a numeric unread count in the left sidebar.
Streams that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All streams
- 2 - Unmuted streams and topics
- 3 - No streams
**Changes**: New in Zulip 8.0 (feature level 210).
schema:
type: integer
enum:
- 1
- 2
- 3
example: 2
- name: enable_stream_desktop_notifications
in: query
description: |
Enable visual desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
description: |
Enable email notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
description: |
Enable mobile notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
description: |
Enable audible desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: notification_sound
in: query
description: |
Notification sound name.
schema:
type: string
example: ding
- name: enable_desktop_notifications
in: query
description: |
Enable visual desktop notifications for direct messages and @-mentions.
schema:
type: boolean
example: true
- name: enable_sounds
in: query
description: |
Enable audible desktop notifications for direct messages and
@-mentions.
schema:
type: boolean
example: true
- name: enable_followed_topic_desktop_notifications
in: query
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: true
- name: enable_followed_topic_email_notifications
in: query
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: true
- name: enable_followed_topic_push_notifications
in: query
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: false
- name: enable_followed_topic_audible_notifications
in: query
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: false
- name: email_notifications_batching_period_seconds
in: query
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
schema:
type: integer
example: 120
- name: enable_offline_email_notifications
in: query
description: |
Enable email notifications for direct messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
description: |
Enable mobile notification for direct messages and @-mentions received
when the user is online.
schema:
type: boolean
example: true
- name: enable_digest_emails
in: query
description: |
Enable digest emails when the user is away.
schema:
type: boolean
example: true
- name: message_content_in_email_notifications
in: query
description: |
Include the message's content in email notifications for new messages.
schema:
type: boolean
example: true
- name: pm_content_in_desktop_notifications
in: query
description: |
Include content of direct messages in desktop notifications.
schema:
type: boolean
example: true
- name: wildcard_mentions_notify
in: query
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
schema:
type: boolean
example: true
- name: enable_followed_topic_wildcard_mentions_notify
in: query
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).
schema:
type: boolean
example: true
- name: desktop_icon_count_display
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: realm_name_in_email_notifications_policy
in: query
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`.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: automatically_follow_topics_policy
in: query
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).
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: automatically_unmute_topics_in_muted_streams_policy
in: query
description: |
Which [topics to unmute automatically in muted streams](/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).
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: automatically_follow_topics_where_mentioned
in: query
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).
schema:
type: boolean
example: true
- name: presence_enabled
in: query
description: |
Display the presence status to other users when online.
schema:
type: boolean
example: true
- name: enter_sends
in: query
description: |
Whether pressing Enter in the compose box sends a message
(or saves a message edit).
schema:
type: boolean
example: true
- name: twenty_four_hour_time
in: query
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.
schema:
type: boolean
example: true
- name: send_private_typing_notifications
in: query
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
direct messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_stream_typing_notifications
in: query
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
stream messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_read_receipts
in: query
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: email_address_visibility
in: query
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
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
example: 1
responses:
"200":
$ref: "#/components/responses/SuccessIgnoredParameters"
/users/me/subscriptions/properties:
post:
operationId: update-subscription-settings
summary: Update subscription settings
tags: ["streams"]
description: |
This endpoint is used to update the user's personal settings for the
streams they are subscribed to, including muting, color, pinning, and
per-stream notification settings.
**Changes**: Prior to Zulip 5.0 (feature level 111), response
object included the `subscription_data` in the the
request. The endpoint now returns the more ergonomic
[`ignored_parameters_unsupported`][ignored-parameters] array instead.
[ignored-parameters]: /api/rest-error-handling#ignored-parameters
parameters:
- name: subscription_data
in: query
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 stream, as well as the `property`
being modified and its new `value`.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
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 stream properties described below:
- `"color"`: The hex value of the user's display color for the stream.
- `"is_muted"`: Whether the stream is [muted](/help/mute-a-stream).<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>
**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`); for
backwards-compatibility, modern Zulip still accepts that property.
- `"pin_to_top"`: Whether to pin the stream at the top of the stream list.
- `"desktop_notifications"`: Whether to show desktop notifications
for all messages sent to the stream.
- `"audible_notifications"`: Whether to play a sound
notification for all messages sent to the stream.
- `"push_notifications"`: Whether to trigger a mobile push
notification for all messages sent to the stream.
- `"email_notifications"`: Whether to trigger an email
notification for all messages sent to the stream.
- `"wildcard_mentions_notify"`: Whether wildcard mentions trigger
notifications as though they were personal mentions in this stream.
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 stream. 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: true
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"
- name: full_name
in: query
description: |
The user's full name.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 5.0 (feature level 106).
schema:
type: string
example: NewName
required: false
- name: role
in: query
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).
schema:
type: integer
example: 400
required: false
- name: profile_data
in: query
description: |
A dictionary containing the to be updated custom profile field data for the user.
content:
application/json:
schema:
type: array
items:
type: object
example:
[{"id": 4, "value": "0"}, {"id": 5, "value": "1909-04-05"}]
required: false
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"
- name: deactivation_notification_comment
in: query
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).
schema:
type: string
example: |
Farewell!
required: false
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 all 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.
parameters:
- name: ordered_linkifier_ids
in: query
description: |
A list of the IDs of all the linkifiers defined in this
organization, in the desired new order.
content:
application/json:
schema:
type: array
items:
type: integer
example: [3, 2, 1, 5]
required: true
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.
parameters:
- $ref: "#/components/parameters/LinkifierPattern"
- $ref: "#/components/parameters/LinkifierURLTemplate"
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
- $ref: "#/components/parameters/LinkifierPattern"
- $ref: "#/components/parameters/LinkifierURLTemplate"
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).
parameters:
- name: name
in: query
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.
schema:
type: string
example: Python playground
required: true
- name: pygments_language
in: query
description: |
The name of the Pygments language lexer for that
programming language.
schema:
type: string
example: Python
required: true
- name: url_template
in: query
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`.
schema:
type: string
example: https://python.example.com?code={code}
required: true
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"
/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
parameters:
- name: apply_markdown
in: query
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)
schema:
type: boolean
default: false
example: true
- 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.
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.
schema:
type: boolean
example: false
- name: include_subscribers
in: query
description: |
Whether each returned stream 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 streams.)
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.
schema:
type: boolean
default: false
example: true
- name: slim_presence
in: query
description: |
Setting this to `true` will make presence dictionaries be keyed by
user ID instead of Zulip API email.
**Changes**: New in Zulip 3.0 (Unstable with no feature level yet).
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/Event_types"
- $ref: "#/components/parameters/AllPublicStreams"
- name: client_capabilities
in: query
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
stream-level notification settings (which means the stream
is not customized and should inherit the user's global
notification settings for stream messages).
<br />
**Changes**: New in Zulip 2.1.0. In earlier Zulip releases,
stream-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 stream 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. **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
content:
application/json:
schema:
type: object
example: {"notification_settings_null": true}
- name: fetch_event_types
in: query
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.
content:
application/json:
schema:
type: array
items:
type: string
example: ["message"]
- $ref: "#/components/parameters/Narrow"
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.
- `CHOICE` 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 new users.
We expect that only official Zulip clients will interact with these data.
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 stream 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 stream 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 stream 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`.
**Changes**: 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.
Users who have been offline for multiple weeks may not appear in this object.
additionalProperties:
type: object
description: |
`{user_id}` or `{user_email}`: Object containing the details of a user's
presence . Depending on the value of `slim_presence`, the object's key is
either the user's ID or the user's Zulip API email.
additionalProperties:
$ref: "#/components/schemas/Presence"
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/Config"
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/Config"
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 stream the user is subscribed to (as well as that user's
personal per-stream settings).
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
**Changes**: 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
streams 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 streams.
**Changes**: Removed `email_address` field from the dictionary
in Zulip 8.0 (feature level 226).
**Changes**: Removed `role` field from the dictionary
in Zulip 6.0 (feature level 133).
never_subscribed:
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
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 stream per week, as
estimated based on recent weeks, rounded to the nearest integer.
If `null`, the stream 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 stream. Included only if `include_subscribers` is `true`.
If a user is not allowed to know the subscribers for
a stream, 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
streams that is visible to the user and the user has never been subscribed
to.
Important for clients containing UI where one can browse streams 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 stream 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 stream. This includes muted streams
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 stream to which the messages were sent.
unread_message_ids:
type: array
description: |
The message IDs of the recent unread messages sent in this stream,
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/BasicStream"
description: |
Present if `stream` is present in `fetch_event_types`.
Array of dictionaries where each dictionary contains details about
a single stream in the organization that is visible to the user.
For organization administrators, this will include all private streams
in the organization.
**Changes**: As of Zulip 8.0 (feature level 205), this will include all
web-public streams in the organization as well.
realm_default_streams:
type: array
items:
$ref: "#/components/schemas/DefaultStream"
description: |
Present if `default_streams` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains details
about a single [default stream](/help/set-default-streams-for-new-users)
for the Zulip organization.
realm_default_stream_groups:
type: array
items:
$ref: "#/components/schemas/DefaultStreamGroup"
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 stream group configured for this
Zulip organization.
Default stream 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:
description: |
`{user_id}`: Object containing the status details of a user
with the key of the object being the ID of the user.
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).
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.
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).
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.
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" - All messages 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 streams](/help/manage-inactive-streams) 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_stream_unreads_count_display_policy:
type: integer
description: |
Configuration for which streams should be displayed with a numeric unread count in the left sidebar.
Streams that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All streams
- 2 - Unmuted streams and topics
- 3 - No streams
**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 stream messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for stream messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for stream messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for stream 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 streams](/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 stream messages. The client should send typing
notifications for stream 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"
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 stream 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 streams.
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
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_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_create_public_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can create public streams
in this organization.
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Admins and moderators only
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams 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
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can create private streams
in this organization.
- 1 = Members only
- 2 = Admins only
- 3 = [Full members][calc-full-member] only
- 4 = Admins and moderators only
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams 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
description: |
Present if `realm` is present in `fetch_event_types`.
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.
The [policy][permission-level] for which users can create web
public streams in this organization. Allowed
values are:
- 2 = Admins only
- 4 = Admins and moderators only
- 6 = Nobody
- 7 = Owners only
**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 streams 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 streams.
- 1 = Any user can use wildcard mentions in large streams.
- 2 = Only members can use wildcard mentions in large streams.
- 3 = Only [full members][calc-full-member] can use wildcard mentions in large streams.
- 5 = Only organization administrators can use wildcard mentions in large streams.
- 6 = Nobody can use wildcard mentions in large streams.
- 7 = Only organization administrators and moderators can use wildcard mentions in large streams.
All users will receive a warning/reminder when using
mentions in large streams, 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). Stream 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
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 stream 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/allow-image-link-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/allow-image-link-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_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 streams 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 `create_web_public_stream_policy` 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_private_message_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
[Policy](/api/roles-and-permissions#permission-levels)
for [who can send direct messages](/help/restrict-direct-messages)
in this organization.
- 1 = Everyone
- 2 = Nobody
**Changes**: New in Zulip 3.0 (feature level 1).
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:
description: |
Boolean describing whether the authentication method (i.e. its key)
is enabled in this organization.
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary of authentication method keys with boolean values that
describe whether the named authentication method is enabled for 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).
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
stream 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
streams 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 streams 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
description: |
Present if `realm` is present in `fetch_event_types`.
The URL for the organization.
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**: 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_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 streams](/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 streams
(`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_notifications_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the stream to which automated messages announcing the
[creation of new streams][new-stream-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-stream-announce]: /help/configure-notification-bot#new-stream-announcements
realm_signup_notifications_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the stream 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-notification-bot#new-user-announcements
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.
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).
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.
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" - All messages 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 streams](/help/manage-inactive-streams) 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_stream_unreads_count_display_policy:
type: integer
description: |
Configuration for which streams should be displayed with a numeric unread count in the left sidebar.
Streams that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All streams
- 2 - Unmuted streams and topics
- 3 - No streams
**Changes**: New in Zulip 8.0 (feature level 210).
enable_stream_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for stream messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for stream messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for stream messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for stream 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 streams](/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
stream 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"
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 stream with the organization's [stream creation
policy](/help/configure-who-can-create-streams). 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 stream.
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 streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
**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 streams.
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 streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
**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 streams.
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 streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
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 streams with
the organization's [streams policy](/help/configure-who-can-invite-to-streams).
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 stream 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
description: |
The organization's canonical URL.
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 streams](/help/public-access-option) and
at least one web-public stream on the server currently
exists. Clients that support viewing content
in web-public streams 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_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).
The `/settings/display` and `/settings/notifications`
endpoints are now deprecated aliases for this endpoint for
backwards-compatibility, and will be removed once clients have
migrated to use this endpoint.
**Changes**: Prior to Zulip 5.0 (feature level 78),
the `/settings` 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 `/settings/notifications` and `/settings/display` endpoints
also had this behavior before they became aliases of `/settings`
in Zulip 5.0 (see feature level 80 change above).
Before these changes, 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
parameters:
- name: full_name
in: query
description: |
A new display name for the user.
schema:
type: string
example: NewName
- name: email
in: query
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.
schema:
type: string
example: newname@example.com
- name: old_password
in: query
description: |
The user's old Zulip password (or LDAP password, if LDAP authentication is in use).
Required only when sending the `new_password` parameter.
schema:
type: string
example: old12345
- name: new_password
in: query
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.
schema:
type: string
example: new12345
- name: twenty_four_hour_time
in: query
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.
schema:
type: boolean
example: true
- name: dense_mode
in: query
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.
schema:
type: boolean
example: true
- name: web_mark_read_on_scroll_policy
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: starred_message_counts
in: query
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.
schema:
type: boolean
example: true
- name: fluid_layout_width
in: query
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.
schema:
type: boolean
example: true
- name: high_contrast_mode
in: query
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.
schema:
type: boolean
example: true
- name: color_scheme
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: enable_drafts_synchronization
in: query
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).
schema:
type: boolean
example: true
- name: translate_emoticons
in: query
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.
schema:
type: boolean
example: true
- name: display_emoji_reaction_users
in: query
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).
schema:
type: boolean
example: false
- name: default_language
in: query
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).
schema:
type: string
example: en
- name: web_home_view
in: query
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" - All messages 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).
schema:
type: string
example: all_messages
- name: web_escape_navigates_to_home_view
in: query
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).
schema:
type: boolean
example: true
- name: left_side_userlist
in: query
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.
schema:
type: boolean
example: true
- name: emojiset
in: query
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).
schema:
type: string
example: "google"
- name: demote_inactive_streams
in: query
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) 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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: user_list_style
in: query
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).
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: web_stream_unreads_count_display_policy
in: query
description: |
Configuration for which streams should be displayed with a numeric unread count in the left sidebar.
Streams that do not have an unread count will have a simple dot indicator for whether there are any
unread messages.
- 1 - All streams
- 2 - Unmuted streams and topics
- 3 - No streams
**Changes**: New in Zulip 8.0 (feature level 210).
schema:
type: integer
enum:
- 1
- 2
- 3
example: 2
- name: timezone
in: query
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).
schema:
type: string
example: "Asia/Kolkata"
- name: enable_stream_desktop_notifications
in: query
description: |
Enable visual desktop notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
description: |
Enable email notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
description: |
Enable mobile notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
description: |
Enable audible desktop notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: notification_sound
in: query
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).
schema:
type: string
example: ding
- name: enable_desktop_notifications
in: query
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.
schema:
type: boolean
example: true
- name: enable_sounds
in: query
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.
schema:
type: boolean
example: true
- name: email_notifications_batching_period_seconds
in: query
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)
schema:
type: integer
example: 120
- name: enable_offline_email_notifications
in: query
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.
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
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.
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
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.
schema:
type: boolean
example: true
- name: enable_followed_topic_desktop_notifications
in: query
description: |
Enable visual desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: true
- name: enable_followed_topic_email_notifications
in: query
description: |
Enable email notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: true
- name: enable_followed_topic_push_notifications
in: query
description: |
Enable push notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: false
- name: enable_followed_topic_audible_notifications
in: query
description: |
Enable audible desktop notifications for messages sent to followed topics.
**Changes**: New in Zulip 8.0 (feature level 189).
schema:
type: boolean
example: false
- name: enable_digest_emails
in: query
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.
schema:
type: boolean
example: true
- name: enable_marketing_emails
in: query
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.
schema:
type: boolean
example: true
- name: enable_login_emails
in: query
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.
schema:
type: boolean
example: true
- name: message_content_in_email_notifications
in: query
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.
schema:
type: boolean
example: true
- name: pm_content_in_desktop_notifications
in: query
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.
schema:
type: boolean
example: true
- name: wildcard_mentions_notify
in: query
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.
schema:
type: boolean
example: true
- name: enable_followed_topic_wildcard_mentions_notify
in: query
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).
schema:
type: boolean
example: true
- name: desktop_icon_count_display
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: realm_name_in_email_notifications_policy
in: query
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.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: automatically_follow_topics_policy
in: query
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).
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: automatically_unmute_topics_in_muted_streams_policy
in: query
description: |
Which [topics to unmute automatically in muted streams](/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).
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
example: 1
- name: automatically_follow_topics_where_mentioned
in: query
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).
schema:
type: boolean
example: true
- name: presence_enabled
in: query
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.
schema:
type: boolean
example: true
- name: enter_sends
in: query
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.
schema:
type: boolean
example: true
- name: send_private_typing_notifications
in: query
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
direct messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_stream_typing_notifications
in: query
description: |
Whether [typing notifications](/help/typing-notifications) be sent when composing
stream messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_read_receipts
in: query
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: email_address_visibility
in: query
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
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
example: 1
responses:
"200":
$ref: "#/components/responses/SuccessIgnoredParameters"
/streams/{stream_id}/members:
get:
operationId: get-subscribers
summary: Get the subscribers of a stream
tags: ["streams"]
description: |
Get all users subscribed to a stream.
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
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 stream.
example:
{"result": "success", "msg": "", "subscribers": [11, 26]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
An example JSON response for when the requested stream does not exist,
or where the user does not have permission to access the target stream:
/streams:
get:
operationId: get-streams
summary: Get all streams
tags: ["streams"]
description: |
Get all streams that the user [has access to](/help/stream-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 streams.
schema:
type: boolean
default: true
example: false
- name: include_web_public
in: query
description: |
Include all web-public streams.
schema:
type: boolean
default: false
example: true
- name: include_subscribed
in: query
description: |
Include all streams that the user is subscribed to.
schema:
type: boolean
default: true
example: false
- name: include_all_active
in: query
description: |
Include all active streams. 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 streams 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 streams 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 stream objects with details on the requested streams.
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
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 stream 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 stream 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 stream is a
[default stream](/help/set-default-streams-for-new-users).
[include_default]: /api/get-streams#parameter-include_default
required:
- stream_id
- name
- description
- date_created
- 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,
"date_created": 1691057093,
"description": "A private stream",
"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 stream</p>",
"stream_id": 2,
"stream_post_policy": 1,
"stream_weekly_traffic": null,
},
{
"can_remove_subscribers_group": 9,
"date_created": 1691057093,
"description": "A default public stream",
"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 stream</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 stream by ID
tags: ["streams"]
description: |
Fetch details for the stream with the ID `stream_id`.
**Changes**: New in Zulip 6.0 (feature level 132).
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
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/BasicStream"
example:
{
"msg": "",
"result": "success",
"stream":
{
"description": "A Scandinavian country",
"first_message_id": 1,
"history_public_to_subscribers": true,
"date_created": 1691057093,
"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/InvalidStreamError"
- description: |
An example JSON response for when the stream ID is not valid:
delete:
operationId: archive-stream
summary: Archive a stream
tags: ["streams"]
description: |
[Archive the stream](/help/archive-a-stream) with the ID `stream_id`.
x-requires-administrator: true
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
An example JSON response for when the supplied stream does not exist:
patch:
operationId: update-stream
summary: Update a stream
tags: ["streams"]
description: |
Configure the stream with the ID `stream_id`. This endpoint supports
an organization administrator editing any property of a stream,
including:
- Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description)
- Stream [permissions](/help/stream-permissions), including
[privacy](/help/change-the-privacy-of-a-stream) and [who can
send](/help/stream-sending-policy).
Note that an organization administrator's ability to change a
[private stream's permissions](/help/stream-permissions#private-streams)
depends on them being subscribed to the stream.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- new_name
- description
- is_private
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
- name: description
in: query
description: |
The new [description](/help/change-the-stream-description) for
the stream, 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 stream description length.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
schema:
type: string
example: "Discuss Italian history and travel destinations."
required: false
allowEmptyValue: true
- name: new_name
in: query
description: |
The new name for the stream.
Clients should use the `max_stream_name_length` returned by the
[`POST /register`](/api/register-queue) endpoint to determine
the maximum stream name length.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
schema:
type: string
example: Italy
required: false
- name: is_private
in: query
description: |
Change whether the stream is a private stream.
schema:
type: boolean
example: true
required: false
- name: is_announcement_only
in: query
deprecated: true
description: |
Whether the stream is limited to announcements.
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
should use `stream_post_policy` instead.
schema:
type: boolean
example: true
required: false
- name: is_web_public
in: query
description: |
Change whether the stream is a web-public stream.
Note that creating web-public streams 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
`create_web_public_stream_policy` realm setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 98).
schema:
type: boolean
example: true
required: false
- name: history_public_to_subscribers
in: query
description: |
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the [shared history](/help/stream-permissions)
option in documentation.
It's an error for this parameter to be false for a public or
web-public stream 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`.
schema:
type: boolean
example: false
required: false
- name: is_default_stream
in: query
description: |
Add or remove the stream as a [default stream][default-stream]
for new users joining the organization.
[default-stream]: /help/set-default-streams-for-new-users
**Changes**: New in Zulip 8.0 (feature level 200). Previously, default stream status
could only be changed using the [dedicated API endpoint](/api/add-default-stream).
schema:
type: boolean
example: false
required: false
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/MessageRetentionDays"
- $ref: "#/components/parameters/CanRemoveSubscribersGroupId"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
An example JSON response for when the supplied stream 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 stream permission
parameters are passed:
/streams/{stream_id}/email_address:
get:
operationId: get-stream-email-address
summary: Get the email address of a stream
tags: ["streams"]
description: |
Get email address of a stream.
**Changes**: New in Zulip 8.0 (feature level 226).
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
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 stream.
example:
{
"result": "success",
"msg": "",
"email": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidStreamError"
- description: |
An example JSON response for when the requested stream does not exist,
or where the user does not have permission to access the target stream:
/streams/{stream_id}/delete_topic:
post:
operationId: delete-topic
summary: Delete a topic
tags: ["streams"]
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 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/StreamIdInPath"
- name: topic_name
in: query
description: |
The name of the topic to delete.
schema:
type: string
example: new coffee machine
required: true
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 stream typing notifications, as no client actually implemented
the previous API for those.
Support for displaying stream typing notifications was new
in Zulip 4.0 (feature level 58). Clients should indicate they support
processing stream 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
parameters:
- name: type
in: query
description: |
Type of the message being composed.
**Changes**: 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.
schema:
type: string
enum:
- direct
- stream
default: direct
example: direct
- name: op
in: query
description: |
Whether the user has started (`"start"`) or stopped (`"stop"`) typing.
schema:
type: string
enum:
- start
- stop
example: start
required: true
- name: to
in: query
description: |
User IDs of the recipients of the message being typed. Required for the
`"direct"` type. Ignored in the case of `"stream"` type. Send a JSON-encoded
list of user IDs. (Use a list 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 stream. A new parameter,
`stream_id`, is now used for this.
Support for typing notifications for stream 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).
content:
application/json:
schema:
type: array
items:
type: integer
minLength: 1
example: [9, 10]
- name: stream_id
in: query
description: |
ID of the stream in which the message is being typed. Required for the `"stream"`
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 stream was passed in `to` parameter.
schema:
type: integer
example: 7
- name: topic
in: query
description: |
Topic to which message is being typed. Required for the `"stream"` 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.
schema:
type: string
example: typing notifications
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 send to multiple streams",
"result": "error",
}
description: |
An example JSON error response for when user sends to multiple streams:
/user_groups/create:
post:
operationId: create-user-group
summary: Create a user group
tags: ["users"]
description: |
Create a new [user group](/help/user-groups).
parameters:
- name: name
in: query
description: |
The name of the user group.
schema:
type: string
example: marketing
required: true
- name: description
in: query
description: |
The description of the user group.
schema:
type: string
example: The marketing team.
required: true
- name: members
in: query
description: |
An array containing the user IDs of the initial members for the
new user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [1, 2, 3, 4]
required: true
- name: can_mention_group
in: query
description: |
ID of the user group whose members are allowed to mention the new
user group.
This setting cannot be set to `"role:internet"` and `"role:owners"`
system groups.
**Changes**: Before Zulip 8.0 (feature level 198),
the `can_mention_group` setting was named `can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups
could be mentioned if and only if they were not system groups.
schema:
type: integer
example: 11
required: false
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"
- name: delete
in: query
description: |
The list of user IDs to be removed from the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [10]
required: false
- name: add
in: query
description: |
The list of user IDs to be added to the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [12, 13]
required: false
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"
- name: name
in: query
description: |
The new name of the group.
**Changes**: Before Zulip 7.0 (feature level 165), this was
a required field.
schema:
type: string
example: marketing team
- name: description
in: query
description: |
The new description of the group.
**Changes**: Before Zulip 7.0 (feature level 165), this was
a required field.
schema:
type: string
example: The marketing team.
- name: can_mention_group
in: query
description: |
ID of the new user group whose members are allowed to mention the
group.
This setting cannot be set to `"role:internet"` and `"role:owners"`
system groups.
**Changes**: Before Zulip 8.0 (feature level 198),
the `can_mention_group` setting was named `can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups
could be mentioned if and only if they were not system groups.
schema:
type: integer
example: 12
required: false
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:
type: integer
description: |
ID of the user group whose members are allowed to mention the group.
**Changes**: Before Zulip 8.0 (feature level 198),
the `can_mention_group` setting was named `can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups
could be mentioned if and only if they were not system groups.
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"
- name: delete
in: query
description: |
The list of user group IDs to be removed from the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [10]
required: false
- name: add
in: query
description: |
The list of user group IDs to be added to the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
required: false
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
get:
operationId: get-user-group-subgroups
summary: Get subgroups of the 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)
parameters:
- $ref: "#/components/parameters/Event_types"
- $ref: "#/components/parameters/Narrow"
- $ref: "#/components/parameters/AllPublicStreams"
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/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: ["streams"]
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 to be configured on the Zulip server.
parameters:
- in: query
name: meeting_name
schema:
type: string
required: true
description: |
Title to use for the BigBlueButton meeting.
A good choice is something like "{stream_name} 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.
BasicStream:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
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 stream 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 stream 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
- 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
DefaultStream:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
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
- 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
BasicStreamBase:
type: object
description: |
Object containing basic details about the stream.
properties:
stream_id:
type: integer
description: |
The unique ID of the stream.
name:
type: string
description: |
The name of the stream.
description:
type: string
description: |
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
rendered_description:
type: string
description: |
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
is_web_public:
type: boolean
description: |
Whether the stream 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 stream.
- 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 stream 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 stream will inherit the organization
level setting.
- `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. `"invite_only": false` implies
`"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
nullable: true
description: |
The ID of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Is `null` for streams with no message history.
**Changes**: New in Zulip 2.1.0.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether the given stream 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 stream.
**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 stream of the bot. If `null`, the bot doesn't
have a default sending stream.
default_events_register_stream:
type: string
nullable: true
description: |
The default stream for which the bot receives events/register data.
If `null`, the bot doesn't have such a default stream.
default_all_public_streams:
type: boolean
description: |
Whether the bot can send messages to all streams 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: |
The "Services" array contains extra configuration fields only relevant
for Outgoing webhook bots and Embedded bots. It 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 containing details extra details. Which fields appear depend
on the type of bot.
oneOf:
- type: object
additionalProperties: false
description: |
When the bot is an outgoing webhook bot.
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: |
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/Config"
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.
Config:
type: object
description: |
A "string: string" dictionary which describes the configuration
for the embedded bot (usually details like API keys).
additionalProperties:
description: |
String describing the config data.
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).
**Changes**: New in Zulip 6.0 (feature level 146).
OnboardingStep:
type: object
additionalProperties: false
description: |
Dictionary containing details of a single onboarding step.
**Changes**: Before Zulip 8.0 (feature level 233), this was
named as `Hotspot`. One-time notice wasn't available earlier.
properties:
type:
type: string
description: |
The type of the onboarding step. Valid values are either
'hotspot' or 'one_time_notice'.
**Changes**: New in Zulip 8.0 (feature level 233).
name:
type: string
description: |
The name of the hotspot.
title:
type: string
description: |
The title of the hotspot, as will be displayed to the user.
description:
type: string
description: |
The description of the hotspot, as will be displayed to the
user.
delay:
type: number
description: |
The delay after which the user should be shown the hotspot.
has_trigger:
type: boolean
description: |
The has_trigger is used to identify if the hotspot will activate
only when some specific event occurs.
**Changes**: New in Zulip 8.0 (feature level 230).
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 realm export.
properties:
id:
type: integer
description: |
The ID of the export.
acting_user_id:
type: integer
description: |
The ID of the user who did the export.
export_time:
type: number
description: |
The UNIX timestamp of when the export was made.
deleted_timestamp:
type: number
nullable: true
description: |
The timestamp of when the export was deleted.
If `null`, it wasn't deleted.
failed_timestamp:
type: number
nullable: true
description: |
The timestamp of when the export failed.
If `null`, it didn't fail.
export_url:
type: string
nullable: true
description: |
The URL of the export. `null` if there's no URL.
pending:
type: boolean
description: |
Whether the export is pending or not.
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:
type: integer
description: |
ID of the user group whose members are allowed to mention the group.
**Changes**: Before Zulip 8.0 (feature level 198),
the `can_mention_group` setting was named `can_mention_group_id`.
New in Zulip 8.0 (feature level 191). Previously, groups
could be mentioned if and only if they were not system groups.
Subscriptions:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
name:
type: string
description: |
The name of a stream.
description:
type: string
description: |
The [description](/help/change-the-stream-description) of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
See also `rendered_description`.
rendered_description:
type: string
description: |
The [description](/help/change-the-stream-description) of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
See also `description`.
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
# 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 stream. 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 stream.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_desktop_notifications, for
this stream.
email_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether email notifications
are enabled for the given stream.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_email_notifications, for
this stream.
wildcard_mentions_notify:
type: boolean
nullable: true
description: |
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this stream.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
push_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether push notifications
are enabled for the given stream.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_push_notifications, for
this stream.
audible_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether audible notifications
are enabled for the given stream.
A `null` value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_audible_notifications, for
this stream.
pin_to_top:
type: boolean
description: |
A boolean specifying whether the given stream has been pinned
to the top.
is_muted:
type: boolean
description: |
Whether the user has muted the stream. Muted streams do
not count towards your total unread count and do not show up in
`All messages` view (previously known as `Home` view).
**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 stream 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 stream.
**Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients
should use `stream_post_policy` instead.
is_web_public:
type: boolean
description: |
Whether the stream 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 stream.
stream_post_policy:
type: integer
description: |
[Policy][permission-level] for which users can post messages to the stream.
- 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 stream 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 stream will inherit the organization
level setting.
- `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. `"invite_only": false` implies
`"history_public_to_subscribers": true`), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
nullable: true
description: |
The ID of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Is `null` for streams with no message history.
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the stream per week, as
estimated based on recent weeks, rounded to the nearest integer.
If `null`, the stream 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 stream.
**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).
DefaultStreamGroup:
type: object
description: |
Dictionary containing details of a default stream
group.
additionalProperties: false
properties:
name:
type: string
description: |
Name of the default stream group.
description:
type: string
description: |
Description of the default stream group.
id:
type: integer
description: |
The ID of the default stream group.
streams:
type: array
description: |
Array containing details about the streams
in the default stream group.
items:
$ref: "#/components/schemas/DefaultStream"
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 stream 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 stream was edited.
The stream 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 stream was edited.
The ID of the stream 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 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 stream, 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 stream 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 stream messages; the ID of the stream.
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`.
Presence:
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.
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 "stream"
messages, this should contain exactly 1 ID, the ID of the
target stream. 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 stream 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 stream messages, it will be the unique ID of the target
stream. 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 stream 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",
}
InvalidStreamError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
example:
{
"msg": "Invalid stream ID",
"code": "BAD_REQUEST",
"result": "error",
}
NonExistingStreamNameError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream:
type: string
description: |
The name of the stream that could not be found.
example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream",
}
NonExistingStreamIdError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream_id:
type: integer
description: |
The stream ID that could not be found.
example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 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:
MissingArgumentError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
## Missing request parameter(s)
A typical failed JSON response for when a required request parameter
is not supplied:
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",
}
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
**Changes**: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's account is deactivated:
RateLimitedError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
## Rate limit exceeded
The `retry-after` parameter in the response indicates how many seconds
the client must wait before making additional requests.
Zulip sets a few [HTTP response headers][rate-limit-headers]
to help with preventing rate limit errors.
**Changes**: The `code` field was not present in rate
limit errors before Zulip 4.0 (feature level 36).
A typical failed JSON response for when a rate limit is exceeded:
[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
**Changes**: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's organization is deactivated:
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:
###################
# 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:
Event_types:
name: event_types
in: query
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.
content:
application/json:
schema:
type: array
items:
type: string
example: ["message"]
required: false
Narrow:
name: narrow
in: query
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 stream subscriptions (or because
they are a recipient of a direct message).
This means that a client that requests a `narrow` filter of
`[["stream", "Denmark"]]` will receive events for new messages
sent to that stream while the user is subscribed to that
stream. 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
streams, so bots using this API need to be
[subscribed](/api/subscribe) to any streams whose messages
you'd like them to process using this endpoint.
See the `all_public_streams` parameter for how to process all
public stream messages in an organization.
Defaults to `[]`.
**Changes**: In Zulip 7.0 (feature level 177), narrows gained support
for three new filters related to direct messages: `is:dm`, `dm` and
`dm-including`; replacing and deprecating `is:private`, `pm-with` and
`group-pm-with` respectively.
content:
application/json:
schema:
type: array
items:
type: array
items:
type: string
default: []
example: [["stream", "Denmark"]]
required: false
AllPublicStreams:
name: all_public_streams
in: query
description: |
Whether you would like to request message events from all public
streams. Useful for workflow bots that you'd like to see all new messages
sent to public streams. (You can also subscribe the user to private streams).
schema:
type: boolean
default: false
example: true
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
StreamIdInPath:
name: stream_id
in: path
description: |
The ID of the stream 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
RequiredContent:
name: content
in: query
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.
schema:
type: string
example: Hello
required: true
OptionalContent:
name: content
in: query
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 stream cannot be changed at the
same time, so sending both `content` and `stream_id` parameters will
throw an error.
schema:
type: string
example: Hello
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
StreamPostPolicy:
name: stream_post_policy
in: query
description: |
[Policy][permission-level] for which users can post messages to the stream.
- 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
schema:
type: integer
default: 1
example: 2
required: false
HistoryPublicToSubscribers:
name: history_public_to_subscribers
in: query
description: |
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the [shared history](/help/stream-permissions)
option in documentation.
schema:
type: boolean
example: false
required: false
IncludeSubscribers:
name: include_subscribers
in: query
description: |
Whether each returned stream 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 streams.)
**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 no offer these
data via the API.
schema:
type: boolean
default: false
example: true
Principals:
name: principals
in: query
description: |
A list of user IDs (preferred) or Zulip API email
addresses of the users to be subscribed to or unsubscribed
from the streams 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).
content:
application/json:
schema:
oneOf:
- type: array
items:
type: string
- type: array
items:
type: integer
example: ["ZOE@zulip.com"]
ReactionType:
name: reaction_type
in: query
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.
schema:
type: string
example: "unicode_emoji"
required: false
EmojiCode:
name: emoji_code
in: query
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.
schema:
type: string
example: "1f419"
required: false
MessageRetentionDays:
name: message_retention_days
in: query
description: |
Number of days that messages sent to this stream 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).
schema:
oneOf:
- type: string
- type: integer
example: "20"
required: false
CanRemoveSubscribersGroupId:
name: can_remove_subscribers_group
in: query
description: |
ID of the [user group](/api/get-user-groups) whose members are
allowed to unsubscribe others from the stream. Note that a user
who is a member of the specified user group must also [have
access](/help/stream-permissions) to the stream 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).
schema:
type: integer
example: 20
required: false
LinkifierPattern:
name: pattern
in: query
description: |
The [Python regular
expression](https://docs.python.org/3/howto/regex.html) that should
trigger the linkifier.
schema:
type: string
example: "#(?P<id>[0-9]+)"
required: true
LinkifierURLTemplate:
name: url_template
in: query
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`.
schema:
type: string
example: https://github.com/zulip/zulip/issues/{id}
required: 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