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 3.1

Feature level 27

• The short_name field is removed from display_recipients in POST /users.

Feature level 26

• The sender_short_name field is no longer included in GET /messages.
• The short_name field is removed from display_recipients in GET /messages.

Changes in Zulip 3.0

Feature level 25

No changes; feature level used for Zulip 3.0 release.

Feature level 24

• The !avatar() and !gravatar() markdown syntax, which was never documented, had inconsistent syntax, and was rarely used, was removed.

Feature level 23

• GET/PUT/POST /users/me/pointer: Removed. Zulip 3.0 removes the pointer concept from Zulip; this legacy data structure was replaced by tracking unread messages and loading views centered on the first unread message.

Feature level 22

• GET /attachments: The date when a message using the attachment was sent is now correctly encoded as date_sent, replacing the confusingly named name field. The date_sent and create_time fields of attachment objects are now encoded as integers; (previously the implementation could send floats incorrectly suggesting that microsecond precision is relevant).
• GET /invites: Now encodes the user ID of the person who created the invitation as invited_by_user_id, replacing the previous ref field (which had that user's Zulip display email address).

Feature level 21

• PATCH /settings/display: Replaced the night_mode boolean with color_scheme as part of supporting automatic night theme detection.

Feature level 20

• Added support for inviting users as organization owners to the invitation endpoints.

Feature level 19

• GET /events: subscriptions event with op="peer_add" and op="peer_remove" now identify the modified stream by a stream_id field, replacing the old name field.

Feature level 18

• POST /register: Added user_avatar_url_field_optional to supported client_capabilities.

Feature level 17

• GET users/me/subscriptions, GET /streams: Added message_retention_days to Stream objects.
• POST users/me/subscriptions, PATCH streams/{stream_id}: Added message_retention_days parameter.

Feature level 16

• [GET /users/me]: Removed pointer from the response, as the "pointer" concept is being removed in Zulip.
• Changed the rendered HTML markup for mentioning a time to use the <time> HTML tag. It is OK for clients to ignore the previous time mention markup, as the feature was not advertised before this change.

Feature level 15

• Added spoilers to supported markdown features.

Feature level 14

• GET users/me/subscriptions: Removed the is_old_stream field from Stream objects. This field was always equivalent to stream_weekly_traffic != null on the same object.

Feature level 13

• POST /register: Added bulk_message_deletion to supported client_capabilities.
• GET /events: message_deleted events have new behavior. The sender and sender_id fields were removed, and the message_id field was replaced by a message_ids list for clients with the bulk_message_deletion client capability. All clients should upgrade; we expect bulk_message_deletion to be required in the future.

Feature level 12

• GET users/{user_id}/subscriptions/{stream_id}: New endpoint added for checking if another user is subscribed to a stream.

Feature level 11

• POST /register: Added realm_community_topic_editing_limit_seconds to the response, the time limit before community topic editing is forbidden. A null value means no limit.
• POST /register: The response now contains a is_owner, similar to the existing is_admin and is_guest fields.
• POST /set-typing-status: Removed legacy support for sending email addresses, rather than user IDs, to encode private message recipients.

Feature level 10

• GET users/me: Added avatar_version, is_guest, is_active, timezone, and date_joined fields to the User objects.
• GET users/me: Removed client_id and short_name from the reponse to this endpoint. These fields had no purpose and were inconsistent with other API responses describing users.

Feature level 9

• POST users/me/subscriptions, DELETE /users/me/subscriptions: Other users to subscribe/unsubscribe, declared in the principals parameter, can now be referenced by user_id, rather than Zulip display email address.
• PATCH /messages/{message_id}: Added send_notification_to_old_thread and send_notification_to_new_thread optional parameters.

Feature level 8

• GET /users, GET /users/{user_id} and GET /users/me: User objects now contain the is_owner field as well.
• Added time mentions to supported markdown features.

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.
• PATCH /users/{user_id}: The is_admin and is_guest parameters were removed in favor of the more general role parameter for specifying a change in user role.
• GET /events: realm_user events sent when a user's role changes now include role property, instead of the previous is_guest or is_admin booleans.
• GET /realm/emoji: The user who uploaded a given custom emoji is now indicated by an author_id field, replacing a previous author object with unnecessary additional data.

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.
• Added new presence_enabled user notification setting; previously presence was always enabled.

Feature level 2:

• 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).
• GET /users/{user_id}: Endpoint added.
• GET /messages: Add support for string-format values for the anchor parameter, deprecating and replacing the use_first_unread_anchor parameter.
• GET /messages and GET /events: Message objects now use topic_links rather than subject_links to indicate links either present in the topic or generated by Linkifiers applied to the topic.
• POST /users/me/subscriptions: Replaced is_announcement_only boolean with stream_post_policy enum for specifying who can post to a stream.
• 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).
• Added EMAIL_ADDRESS_VISIBILITY_NOBODY possible value for email_address_visibility.
• Added private_message_policy realm setting.
• 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.
• Added /export/realm endpoints for triggering a data export.
• PATCH /realm: Added invite_to_stream_policy, create_stream_policy, digest_emails_enabled, digest_weekday, user_group_edit_policy, and avatar_changes_disabled organization settings.
• Added fluid_layout_width, desktop_icon_count_display, and demote_inactive_streams display settings.
• enable_stream_sounds was renamed to enable_stream_audible_notifications.
• Deprecated in_home_view, replacing it with the more readable is_muted (with the opposite meaning).
• Custom profile fields: Added EXTERNAL_ACCOUNT field type.

Changes in Zulip 2.0

• POST /messages: Added support for using user IDs and stream IDs for specifying the recipients of a message.
• POST /messages, POST /messages/{message_id}: Added support for encoding topics using the topic parameter name. The previous subject parameter name was deprecated but is still supported for backwards-compatibility.
• POST /set-typing-status: Added support for specifying the recipients with user IDs, deprecating the original API of specifying them using email addresses.

Changes not yet stabilized

• POST /register: Added slim_presence parameter. Changes the format of presence events, but is still being changed and should not be used by clients.