Real-time events

Specialty endpoints

Changelog

This page documents changes to the Zulip Server API over time.

The recommended way for a client like the Zulip mobile or desktop apps
that needs to support interaction with a wide range of different Zulip
server versions is to check the zulip_feature_level parameter in the
/register and /server_settings responses to determine which of the
below features are supported.

Changes in Zulip 2.2

Feature level 7
* GET /events: realm_user and
realm_bot events no longer contain an email field to identify
the user; use the user_id field instead. Previously, some (but
not all) events of these types contained an email key in addition to
to user_id) for identifying the modified user.

Feature level 6
* GET /events: realm_user events to
update a user's avatar now include the avatar_version field, which
is important for correctly refetching medium-size avatar images when
the user's avatar changes.
* GET /users and GET
/users/{user_id}: User objects now contain the
avatar_version field as well.

Feature level 5
* GET /events: realm_bot events,
sent when changes are made to bot users, now contain an
integer-format owner_id field, replacing the owner field (which
was an email address).

Feature level 4

jitsi_server_url, development_environment, server_generation,
password_min_length, password_min_guesses, max_file_upload_size_mib,
max_avatar_file_size_mib, server_inline_image_preview,
server_inline_url_embed_preview, server_avatar_changes_disabled and
server_name_changes_disabled fields are now available via
POST /register to make them accessible to all the clients;
they were only internally available to Zulip's web app prior to this.

Feature level 3:

zulip_version and zulip_feature_level are always returned
in POST /register; previously they were only returned if event_types
included zulip_version.

POST /messages/{message_id}/reactions:
The reaction_type parameter is optional; the server will guess the
reaction_type if it is not specified (checking custom emoji, then
unicode emoji for any with the provided name).

reactions objects returned by the API (both in GET /messages and
in GET /events) now include the user who reacted in a top-level
user_id field. The legacy user dictionary (which had
inconsistent format between those two endpoints) is deprecated.

Feature level 1:

GET /server_settings: Added
zulip_feature_level, which can be used by clients to detect which
of the features described in this changelog are supported.

POST /register: Added zulip_feature_level
to the response if zulip_version is among the requested
event_types.

GET /users: User objects for bots now
contain a bot_owner_id, replacing the previous bot_owner field
(which had the email address of the bot owner).

PATCH /streams/{stream_id}: Replaced
is_announcement_only boolean with stream_post_policy enum for
specifying who can post to a stream.

GET /streams: Replaced
is_announcement_only boolean with stream_post_policy enum for
specifying who can post to a stream.

GET /api/v1/user_uploads: Added new endpoint for requesting a
temporary URL for an uploaded file that does not require
authentication to access (e.g. for passing from a Zulip desktop,
mobile, or terminal app to the user's default browser).

muted_topic objects now are a 3-item tuple: (stream_id, topic,
date_muted). Previously, they were a 2-item tuple.

GitLab authentication is now available.

Added None as a video call provider option.

Changes in Zulip 2.1

GET /users: Added include_custom_profile_fields
to request custom profile field data.

GET /users/me: Added avatar_url field,
containing the user's avatar URL, to the response.

GET /users/me/subscriptions: Added
include_subscribers parameter controlling whether data on the
other subscribers is included. Previous behavior was to always send
subscriber data.

GET /users/me/subscriptions:
Stream-level notification settings like push_notifications were
changed to be nullable boolean fields (true/false/null), with null
meaning that the stream inherits the organization-level default.
Previously, the only values were true/false. A client communicates
support for this feature using client_capabilities.

GET /users/me/subscriptions: Added
wildcard_mentions_notify notification setting, with the same
global-plus-stream-level-override model as other notification settings.

GET /server_settings: Added
external_authentication_methods structure, used to display login
buttons nicely in the mobile apps.

Added first_message_id field to Stream objects. This is helpful
for determining whether the stream has any messages older than a
window cached in a client.

Added is_web_public field to Stream objects. This field is
intended to support web-public streams.