30 KiB
API Changelog
This page documents changes to the Zulip Server API over time. See also the Zulip server changelog.
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 5.0
Feature level 90
- We no longer include
sender_ids
in thestreams
section ofUnreadMessagesResult
, which becomes theunread_msgs
section of the events that clients fetch when registering events at page load time. (We don't believe this feature has ever been used in a meaningful way.)
Feature level 89
GET /events
: Introduced theuser_settings
event type, unifying and replacing the previousupdate_display_settings
andupdate_global_notifications
event types. The legacy event types are still supported for backwards compatibility, but will be removed in a future release.POST /register
: Addeduser_settings
field in the response, which is a dictionary containing all the user's personal settings. For backwards-compatibility, individual settings will still appear in the top-level response for clients don't support theuser_settings_object
client capability.POST /register
: Added theuser_settings_object
property to supportedclient_capabilities
. When enabled, the server will not include a duplicate copy of personal settings in the top-level response.GET /events
:update_display_settings
andupdate_global_notifications
events now only sent to clients that did not includeuser_settings_object
in theirclient_capabilities
when the event queue was created.
Feature level 88
POST /register
: Addedzulip_merge_base
field to the response.GET /events
: Added newzulip_merge_base
field to therestart
event.GET /server_settings
: Addedzulip_merge_base
to the responses which can be used to make "About Zulip" widgets in clients.
Feature level 87
-
PATCH /settings
: Added a newenable_drafts_synchronization
setting, which controls whether the syncing drafts between different clients is enabled. -
GET /events
,POST /register
: Added newenable_drafts_synchronization
setting underupdate_display_settings
. -
GET /drafts
: Added new endpoint to fetch user's synced drafts from the server. -
POST /drafts
: Added new endpoint to create drafts when syncing has been enabled. -
PATCH /drafts/{draft_id}
: Added new endpoint to edit a draft already owned by the user. -
DELETE /drafts/{draft_id}
: Added new endpoint to delete a draft already owned by the user.
Feature level 86
GET /events
: Addedemoji_name
,emoji_code
, andreaction_type
fields touser_status
objects.POST /register
: Addedemoji_name
,emoji_code
, andreaction_type
fields touser_status
objects.POST /users/me/status
: Added support for newemoji_name
,emoji_code
, andreaction_type
parameters.
Feature level 85
POST /register
,PATCH /realm
: Replacedadd_emoji_by_admins_only
field with an integer fieldadd_custom_emoji_policy
.
Feature level 84
POST /register
: Theenter_sends
setting is now sent whenupdate_display_setting
is present infetch_event_types
instead ofrealm_user
.
Feature level 83
-
POST /register
: Thecross_realm_bots
section of the response now uses theis_system_bot
flag to indicate whether the bot is a system bot.
Feature level 82
PATCH /settings
now accepts a newemail_notifications_batching_period_seconds
field for setting the time duration for which the server will collect email notifications before sending them.
Feature level 81
POST /users/me/enter-sends
has been removed. Theenter_sends
setting is now edited using the normalPATCH /settings
endpoint.
Feature level 80
PATCH /settings
: The/settings/notifications
and/settings/display
endpoints were merged into the main/settings
endpoint; now all personal settings should be edited using that single endpoint. The old URLs are preserved as deprecated aliases for backwards compatibility.
Feature level 79
GET /users/me/subscriptions
: Thesubscribers
field now returns user IDs ifinclude_subscribers
is passed. Previously, this endpoint returned user display email addresses in this field.GET /streams/{stream_id}/members
: This endpoint now returns user IDs. Previously, it returned display email addresses.
Feature level 78
-
PATCH /settings
: Addedignored_parameters_unsupported
field, which is a list of parameters that were ignored by the endpoint, to the response object. -
PATCH /settings
: Removedfull_name
andaccount_email
fields from the response object.
Feature level 77
GET /events
: Removedrecipient_id
andsender_id
field in responses ofdelete_message
event whenmessage_type
isprivate
.
Feature level 76
POST /fetch_api_key
,POST /dev_fetch_api_key
: The HTTP status for authentication errors is now 401. This was previously 403.- All API endpoints now use the HTTP 401 error status for API requests involving a deactivated user or realm. This was previously 403.
- Mobile push notifications now include the
mentioned_user_group_id
andmentioned_user_group_name
fields when a user group containing the user is mentioned. Previously, these were indistinguishable from personal mentions (as both types havetrigger="mention"
).
Feature level 75
POST /register
,PATCH /realm
: Replacedallow_community_topic_editing
field with an integer fieldedit_topic_policy
.
Feature level 74
POST /register
: Addedserver_needs_upgrade
andevent_queue_longpoll_timeout_seconds
field when fetching realm data.
Feature level 73
GET /users
,GET /users/{user_id}
,GET /users/{email}
andGET /users/me
: Addedis_billing_admin
field to returned user objects.GET /events
: Addedis_billing_admin
field to user objects sent inrealm_user
events.POST /register
: Addedis_billing_admin
field in the user objects returned in therealm_users
field.
Feature level 72
POST /register
: Renamedmax_icon_file_size
tomax_icon_file_size_mib
,realm_upload_quota
torealm_upload_quota_mib
andmax_logo_file_size
tomax_logo_file_size_mib
.
Feature level 71
GET /events
: Addedis_web_public
field tostream
events changinginvite_only
.
Feature level 70
POST /register
: Added new top-levelserver_timestamp
field when fetching presence data, to match the existing presence API.
Feature levels 66-69 are reserved for future use in 4.x maintenance releases.
Changes in Zulip 4.0
Feature level 65
No changes; feature level used for Zulip 4.0 release.
Feature level 64
PATCH /streams/{stream_id}
: Removed unnecessary JSON-encoding of string parametersnew_name
anddescription
.PATCH /settings/display
: Removed unnecessary JSON-encoding of string parametersdefault_view
,emojiset
andtimezone
.
Feature level 63
PATCH /settings/notifications
: Removed unnecessary JSON-encoding of string parameternotification_sound
.PATCH /settings/display
: Removed unnecessary JSON-encoding of string parameterdefault_language
.POST /users/me/tutorial_status
: Removed unnecessary JSON-encoding of string parameterstatus
.POST /realm/domains
: Removed unnecessary JSON-encoding of string parameterdomain
.PATCH /default_stream_groups/{user_id}
: Removed unnecessary JSON-encoding of string parametersnew_group_name
andnew_description
.POST /users/me/hotspots
: Removed unnecessary JSON-encoding of string parameterhotspot
.
Feature level 62
- Added
moderators only
option forwildcard_mention_policy
.
Feature level 61
- Added support for inviting users as moderators to the invitation endpoints.
Feature level 60
POST /register
: Added a new boolean fieldis_moderator
, similar to the existingis_admin
,is_owner
andis_guest
fields, to the response.PATCH /users/{user_id}
: Added support for changing a user's organization-level role to moderator.- API endpoints that return
role
values can now return300
, the encoding of the moderator role.
Feature level 59
GET /users
,GET /users/{user_id}
,GET /users/{email}
andGET /users/me
: Addedrole
field to returned user objects.GET /events
: Addedrole
field to user objects sent inrealm_user
events.POST /register
: Addedrole
field in the user objects returned in therealm_users
field.GET /events
: Added newzulip_version
andzulip_feature_level
fields to therestart
event.
Feature level 58
POST /register
: Added the newstream_typing_notifications
property to supportedclient_capabilities
.GET /events
: Extended format fortyping
events to support typing notifications in stream messages. These new events are only sent to clients withclient_capabilities
showing support forstream_typing_notifications
.POST /set-typing-status
: Added support for sending typing notifications for stream messages.
Feature level 57
PATCH /realm/filters/{filter_id}
: New endpoint added to update a realm linkifier.
Feature level 56
POST /register
: Added a new settingmove_messages_between_streams_policy
for controlling who can move messages between streams.
Feature level 55
POST /register
: Addedrealm_giphy_rating
andgiphy_rating_options
fields.PATCH /realm
: Addedgiphy_rating
parameter.
Feature level 54
GET /realm/filters
has been removed and replace withGET /realm/linkifiers
which returns the data in a cleaner dictionary format.GET /events
: Introduced new event typerealm_linkifiers
. The previousrealm_filters
event type is still supported for backwards compatibility, but will be removed in a future release.POST /register
: The response now supports arealm_linkifiers
event type, containing the same data as the legacyrealm_filters
key, with a more extensible object format. The previousrealm_filters
event type is still supported for backwards compatibility, but will be removed in a future release. The legacyrealm_filters
key is deprecated but remains available for backwards compatibility.
Feature level 53
POST /register
: Addedmax_topic_length
andmax_message_length
, and renamedmax_stream_name_length
andmax_stream_description_length
to allow clients to transparently support these values changing in a future server version.
Feature level 52
PATCH /realm
: Removed unnecessary JSON-encoding of string parametersname
,description
,default_language
, anddefault_code_block_language
.
Feature level 51
POST /register
: Added a new boolean fieldcan_invite_others_to_realm
.
Feature level 50
POST /register
: Replacedinvite_by_admins_only
field with an integer fieldinvite_to_realm_policy
.
Feature level 49
- Added new
POST /realm/playground
andDELETE /realm/playground/{playground_id}
endpoints for code playgrounds. GET /events
: A newrealm_playgrounds
events is sent when changes are made to a set of configured code playgrounds for an organization.POST /register
: Added a newrealm_playgrounds
field, which is required to fetch the set of configured code playgrounds for an organization.
Feature level 48
POST /users/me/muted_users/{muted_user_id}
,DELETE /users/me/muted_users/{muted_user_id}
: New endpoints added to mute/unmute users.GET /events
: Added new event typemuted_users
which will be sent to a user when the set of users muted by them has changed.
Feature level 47
POST /register
: Added a newgiphy_api_key
field, which is required to fetch GIFs using the GIPHY API.
Feature level 46
GET /messages
andGET /events
: Thetopic_links
field now contains a list of dictionaries, rather than a list of strings.
Feature level 45
GET /events
: Removed uselessop
field fromcustom_profile_fields
events. These events contain the full set of configuredcustom_profile_fields
for the organization regardless of what triggered the change.
Feature level 44
POST /register
: extended theunread_msgs
object to includeold_unreads_missing
, which indicates whether the server truncated theunread_msgs
due to excessive total unread messages.
Feature level 43
- [
GET /users/{user_id_or_email}/presence
]: Added support for passing theuser_id
to identify the target user.
Feature level 42
PATCH /settings/display
: Added a newdefault_view
setting allowing the user to set the default view.
Feature level 41
GET /events
: Removedname
field from update subscription events.
Feature level 40
GET /events
: Removedemail
field from update subscription events.
Feature level 39
- Added new GET /users/{email} endpoint.
Feature level 38
POST /register
: Increasedrealm_community_topic_editing_limit_seconds
time limit value to 259200s (3 days).
Feature level 37
- Consistently provide
subscribers
in stream data when clients register for subscriptions withinclude_subscribers
, even if the user can't access subscribers.
Feature level 36
POST /users
: Restricted access to organization administrators with thecan_create_users
permission.- Error handling: The
code
property will not be present in errors due to rate limits.
Feature level 35
- The peer_add and peer_remove subscription events now have plural
versions of
user_ids
andstream_ids
.
Feature level 34
POST /register
: Added a newwildcard_mention_policy
setting for controlling who can use wildcard mentions in large streams.
Feature level 33
- Markdown code blocks now have a
data-code-language
attribute attached to the outerdiv
element, recording the programming language that was selecting for syntax highlighting. This field supports the upcoming "view in playground" feature for code blocks.
Feature level 32
GET /events
: Addedop
field toupdate_message_flags
events, deprecating theoperation
field (which has the same value). This removes an unintentional anomaly in the format of this event type.
Feature level 31
-
GET users/me/subscriptions
: Added arole
field to Subscription objects representing whether the user is a stream administrator. -
GET /events
: Addedrole
field to Subscription objects sent insubscriptions
events.
Note that as of this feature level, stream administrators are a partially completed feature. In particular, it is impossible for a user to be a stream administrator at this feature level.
Feature level 30
GET users/me/subscriptions
,GET /streams
: Addeddate_created
to Stream objects.POST /users
,POST /bots
: The ID of the newly created user is now returned in the response.
Feature levels 28 and 29 are reserved for future use in 3.x bug fix releases.
Changes in Zulip 3.1
Feature level 27
- The
short_name
field is removed fromdisplay_recipients
inPOST /users
.
Feature level 26
- The
sender_short_name
field is no longer included inGET /messages
. - The
short_name
field is removed fromdisplay_recipients
inGET /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 thepointer
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 asdate_sent
, replacing the confusingly namedname
field. Thedate_sent
andcreate_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 asinvited_by_user_id
, replacing the previousref
field (which had that user's Zulip display email address).
Feature level 21
PATCH /settings/display
: Replaced thenight_mode
boolean withcolor_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 withop="peer_add"
andop="peer_remove"
now identify the modified stream by astream_id
field, replacing the oldname
field.
Feature level 18
POST /register
: Addeduser_avatar_url_field_optional
to supportedclient_capabilities
.
Feature level 17
GET users/me/subscriptions
,GET /streams
: Addedmessage_retention_days
to Stream objects.POST users/me/subscriptions
,PATCH streams/{stream_id}
: Addedmessage_retention_days
parameter.
Feature level 16
- [
GET /users/me
]: Removedpointer
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 theis_old_stream
field from Stream objects. This field was always equivalent tostream_weekly_traffic != null
on the same object.
Feature level 13
POST /register
: Addedbulk_message_deletion
to supportedclient_capabilities
.GET /events
:message_deleted
events have new behavior. Thesender
andsender_id
fields were removed, and themessage_id
field was replaced by amessage_ids
list for clients with thebulk_message_deletion
client capability. All clients should upgrade; we expectbulk_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
: Addedrealm_community_topic_editing_limit_seconds
to the response, the time limit before community topic editing is forbidden. Anull
value means no limit. This was previously hard-coded in the server as 86400 seconds (1 day).POST /register
: The response now contains ais_owner
, similar to the existingis_admin
andis_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
: Addedavatar_version
,is_guest
,is_active
,timezone
, anddate_joined
fields to the User objects.GET users/me
: Removedclient_id
andshort_name
from the response 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 theprincipals
parameter, can now be referenced by user_id, rather than Zulip display email address.- PATCH /messages/{message_id}: Added
send_notification_to_old_thread
andsend_notification_to_new_thread
optional parameters.
Feature level 8
GET /users
,GET /users/{user_id}
andGET /users/me
: User objects now contain theis_owner
field as well.- Added time mentions to supported Markdown features.
Feature level 7
GET /events
:realm_user
andrealm_bot
events no longer contain anemail
field to identify the user; use theuser_id
field instead. Previously, some (but not all) events of these types contained anemail
key in addition to touser_id
) for identifying the modified user.PATCH /users/{user_id}
: Theis_admin
andis_guest
parameters were removed in favor of the more generalrole
parameter for specifying a change in user role.GET /events
:realm_user
events sent when a user's role changes now includerole
property, instead of the previousis_guest
oris_admin
booleans.GET /realm/emoji
: The user who uploaded a given custom emoji is now indicated by anauthor_id
field, replacing a previousauthor
object with unnecessary additional data.
Feature level 6
GET /events
:realm_user
events to update a user's avatar now include theavatar_version
field, which is important for correctly refetching medium-size avatar images when the user's avatar changes.GET /users
andGET /users/{user_id}
: User objects now contain theavatar_version
field as well.
Feature level 5
GET /events
:realm_bot
events, sent when changes are made to bot users, now contain an integer-formatowner_id
field, replacing theowner
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
andserver_name_changes_disabled
fields are now available viaPOST /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
andzulip_feature_level
are always returned inPOST /register
; previously they were only returned ifevent_types
includedzulip_version
.- Added new
presence_enabled
user notification setting; previously presence was always enabled.
Feature level 2:
POST /messages/{message_id}/reactions
: Thereaction_type
parameter is optional; the server will guess thereaction_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 inGET /messages
and inGET /events
) now include the user who reacted in a top-leveluser_id
field. The legacyuser
dictionary (which had inconsistent format between those two endpoints) is deprecated.
Feature level 1:
GET /server_settings
: Addedzulip_feature_level
, which can be used by clients to detect which of the features described in this changelog are supported.POST /register
: Addedzulip_feature_level
to the response ifzulip_version
is among the requestedevent_types
.GET /users
: User objects for bots now contain abot_owner_id
, replacing the previousbot_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 theanchor
parameter, deprecating and replacing theuse_first_unread_anchor
parameter.GET /messages
andGET /events
: Message objects now usetopic_links
rather thansubject_links
to indicate links either present in the topic or generated by linkifiers applied to the topic.POST /users/me/subscriptions
: Replacedis_announcement_only
boolean withstream_post_policy
enum for specifying who can post to a stream.PATCH /streams/{stream_id}
: Replacedis_announcement_only
boolean withstream_post_policy
enum for specifying who can post to a stream.GET /streams
: Replacedis_announcement_only
boolean withstream_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 foremail_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
: Addedinclude_custom_profile_fields
to request custom profile field data.GET /users/me
: Addedavatar_url
field, containing the user's avatar URL, to the response.GET /users/me/subscriptions
: Addedinclude_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 likepush_notifications
were changed to be nullable boolean fields (true/false/null), withnull
meaning that the stream inherits the organization-level default. Previously, the only values were true/false. A client communicates support for this feature usingclient_capabilities
.GET /users/me/subscriptions
: Addedwildcard_mentions_notify
notification setting, with the same global-plus-stream-level-override model as other notification settings.GET /server_settings
: Addedexternal_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
: Addedinvite_to_stream_policy
,create_stream_policy
,digest_emails_enabled
,digest_weekday
,user_group_edit_policy
, andavatar_changes_disabled
organization settings.- Added
fluid_layout_width
,desktop_icon_count_display
, anddemote_inactive_streams
display settings. enable_stream_sounds
was renamed toenable_stream_audible_notifications
.- Deprecated
in_home_view
, replacing it with the more readableis_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 thetopic
parameter name. The previoussubject
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
: Addedslim_presence
parameter. Changes the format of presence events, but is still being changed and should not be used by clients.