First message ...zulip.txt
', "recipient_id": 23, "timestamp": 1594825416, "client": "test suite", "subject": "test", "topic_links": [], "is_me_message": false, "reactions": [], "submessages": [], "sender_full_name": "King Hamlet", "sender_email": "user10@zulip.testserver", "sender_realm_str": "zulip", "display_recipient": "Denmark", "type": "stream", "stream_id": 1, "avatar_url": null, "content_type": "text/html", }, "flags": [], "id": 1, } - type: object description: | Event sent to a user's clients when the user completes the OAuth flow for the [Zoom integration](/help/start-a-call). Clients need to know whether initiating Zoom OAuth is required before creating a Zoom call. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - has_zoom_token value: type: boolean description: | A boolean specifying whether the user has zoom token or not. additionalProperties: false example: { "type": "has_zoom_token", "value": true, "id": 0, } - type: object description: | A simple event sent when the set of invitations changes. This event is sent to organization administrators and the creator of the changed invitation; this tells clients they need to refetch data from `GET /invites` if they are displaying UI containing active invitations. **Changes**: Before Zulip 8.0 (feature level 209), this event was only sent to organization administrators. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - invites_changed additionalProperties: false example: {"type": "invites_changed", "id": 0} - type: object description: | Event sent to all users in a Zulip organization when a new user joins or when a guest user gains access to a user. Processing this event is important to being able to display basic details on other users given only their ID. If the current user is a guest whose access to a newly created user is limited by a `can_access_all_users_group` policy, and the event queue was registered with the `user_list_incomplete` client capability, then the event queue will not receive an event for such a new user. If a newly created user is inaccessible to the current user via such a policy, but the client lacks `user_list_incomplete` client capability, then this event will be delivered to the queue, with an "Unknown user" object with the usual format but placeholder data whose only variable content is the user ID. **Changes**: Before Zulip 8.0 (feature level 232), the `user_list_incomplete` client capability did not exist, and so all clients whose access to a new user was prevented by `can_access_all_users_group` policy would receive a fake "Unknown user" event for such a user. Starting with Zulip 8.0 (feature level 228), this event is also sent when a guest user gains access to a user. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - realm_user op: type: string enum: - add person: $ref: "#/components/schemas/User" additionalProperties: false example: { "type": "realm_user", "op": "add", "person": { "email": "foo@zulip.com", "delivery_email": null, "user_id": 38, "avatar_version": 1, "is_admin": false, "is_owner": false, "is_guest": false, "is_billing_admin": false, "role": 400, "is_bot": false, "full_name": "full name", "timezone": "", "is_active": true, "date_joined": "2020-07-15T15:04:02.030833+00:00", "avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1", "profile_data": {}, }, "id": 0, } - type: object description: | Event sent to guest users when they lose access to a user. **Changes**: As of Zulip 8.0 (feature level 228), this event is no longer deprecated. In Zulip 8.0 (feature level 222), this event was deprecated and no longer sent to clients. Prior to this feature level, it was sent to all users in a Zulip organization when a user was deactivated. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - realm_user op: type: string enum: - remove person: type: object additionalProperties: false description: | Object containing details of the deactivated user. properties: user_id: type: integer description: | The ID of the deactivated user. full_name: type: string deprecated: true description: | The full name of the user. **Deprecated**: We expect to remove this field in the future. additionalProperties: false example: { "type": "realm_user", "op": "remove", "person": {"user_id": 35, "full_name": "Foo Bot"}, "id": 0, } - type: object description: | Event sent to all users in an organization when a user comes back online after being offline for a while. While most presence updates are done via polling the [main presence endpoint](/api/get-presence), this event is important to avoid confusing users when someone comes online and immediately sends a message (one wouldn't want them to still appear offline at that point!). If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is set to `true`, then the event is only sent to users who can access the user who came back online. **Changes**: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - presence user_id: type: integer description: | The ID of the modified user. email: type: string description: | The Zulip API email of the user. **Deprecated**: This field will be removed in a future release as it is redundant with the `user_id`. deprecated: true server_timestamp: type: number description: | The timestamp of when the Zulip server received the user's presence as a UNIX timestamp. presence: type: object description: | Object containing the details of the user's most recent presence. additionalProperties: type: object description: | `{client_name}`: Object containing the details of the user's presence. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always be `"website"` as the server no longer stores which client submitted presence updates. Previously, the object key was the client's platform name, for example `website` or `ZulipDesktop`. additionalProperties: false properties: client: type: string description: | The client's platform name. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always be `"website"` as the server no longer stores which client submitted presence updates. status: type: string enum: - idle - active description: | The status of the user on this client. Will be either `idle` or `active`. timestamp: type: integer description: | The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second. pushable: type: boolean description: | Whether the client is capable of showing mobile/push notifications to the user. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always be `false` as the server no longer stores which client submitted presence updates. additionalProperties: false example: { "type": "presence", "user_id": 10, "email": "user10@zulip.testserver", "server_timestamp": 1594825445.320078373, "presence": { "website": { "client": "website", "status": "idle", "timestamp": 1594825445, "pushable": false, }, }, "id": 0, } - type: object description: | Event sent when a new channel is created to users who can see the new channel exists (for private channels, only subscribers and organization administrators will receive this event). This event is also sent when a user gains access to a channel they previously [could not access](/help/channel-permissions), such as when their [role](/help/roles-and-permissions) changes, a private channel is made public, or a guest user is subscribed to a public (or private) channel. Note that organization administrators who are not subscribed will not be able to see content on the channel; just that it exists. **Changes**: Prior to Zulip 8.0 (feature level 220), this event was incorrectly not sent to guest users a web-public channel was created. Prior to Zulip 8.0 (feature level 205), this event was not sent when a user gained access to a channel due to their role changing. Prior to Zulip 8.0 (feature level 192), this event was not sent when guest users gained access to a public channel by being subscribed. Prior to Zulip 6.0 (feature level 134), this event was not sent when a private channel was made public. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - create streams: type: array description: | Array of objects, each containing details about the newly added channel(s). items: $ref: "#/components/schemas/BasicChannel" additionalProperties: false example: { "type": "stream", "op": "create", "streams": [ { "name": "private", "stream_id": 12, "description": "", "rendered_description": "", "date_created": 1691057093, "creator_id": 11, "invite_only": true, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": false, "first_message_id": null, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, "stream_weekly_traffic": null, }, ], "id": 0, } - type: object description: | Event sent to all users who can see a channel when it is deactivated. This event is also sent when a user loses access to a channel they previously [could access](/help/channel-permissions) because they are unsubscribed from a private channel or their [role](/help/roles-and-permissions) has changed. **Changes**: Prior to Zulip 8.0 (feature level 205), this event was not sent when a user lost access to a channel due to their role changing. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - delete streams: type: array description: | Array of objects, each containing details about a channel that was deleted. items: $ref: "#/components/schemas/BasicChannel" additionalProperties: false example: { "type": "stream", "op": "delete", "streams": [ { "name": "private", "stream_id": 12, "description": "", "rendered_description": "", "date_created": 1691057093, "creator_id": 11, "invite_only": true, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": false, "first_message_id": null, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, "stream_weekly_traffic": null, }, ], "id": 0, } - type: object description: | Event sent to all users who can see that a channel exists when a property of that channel changes. See [GET /streams](/api/get-streams#response) response for details on the various properties of a channel. **Changes**: Before Zulip 9.0 (feature level 256), this event was never sent when the `first_message_id` property of a channel was updated because the oldest message that had been sent to it changed. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - update stream_id: type: integer description: | The ID of the channel whose details have changed. name: type: string description: | The name of the channel whose details have changed. property: type: string description: | The property of the channel which has changed. See [GET /streams](/api/get-streams#response) response for details on the various properties of a channel. Clients should handle an "unknown" property received here without crashing, since that can happen when connecting to a server running a newer version of Zulip with new features. value: description: | The new value of the changed property. oneOf: - type: integer - type: boolean - type: string rendered_description: type: string description: | Note: Only present if the changed property was `description`. The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. history_public_to_subscribers: type: boolean description: | Note: Only present if the changed property was `invite_only`. Whether the history of the channel is public to its subscribers. Currently always true for public channels (i.e. `"invite_only": false` implies `"history_public_to_subscribers": true`), but clients should not make that assumption, as we may change that behavior in the future. is_web_public: type: boolean description: | Note: Only present if the changed property was `invite_only`. Whether the channel's history is now readable by web-public spectators. **Changes**: New in Zulip 5.0 (feature level 71). additionalProperties: false example: { "op": "update", "type": "stream", "property": "invite_only", "value": true, "history_public_to_subscribers": true, "is_web_public": false, "stream_id": 11, "name": "test", "id": 0, } - type: object description: | Event sent when a reaction is added to a message. Sent to all users who were recipients of the message. allOf: - $ref: "#/components/schemas/EmojiReactionEvent" - additionalProperties: false properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - reaction op: type: string enum: - add message_id: type: integer description: | The ID of the message to which a reaction was added. emoji_code: {} emoji_name: {} reaction_type: {} user_id: {} user: {} example: { "type": "reaction", "op": "add", "user_id": 10, "user": { "user_id": 10, "email": "user10@zulip.testserver", "full_name": "King Hamlet", }, "message_id": 32, "emoji_name": "tada", "emoji_code": "1f389", "reaction_type": "unicode_emoji", "id": 0, } - type: object description: | Event sent when a reaction is removed from a message. Sent to all users who were recipients of the message. allOf: - $ref: "#/components/schemas/EmojiReactionEvent" - additionalProperties: false properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - reaction op: type: string enum: - remove message_id: type: integer description: | The ID of the message from which the reaction was removed. emoji_code: {} emoji_name: {} reaction_type: {} user_id: {} user: {} example: { "type": "reaction", "op": "remove", "user_id": 10, "user": { "user_id": 10, "email": "user10@zulip.testserver", "full_name": "King Hamlet", }, "message_id": 52, "emoji_name": "tada", "emoji_code": "1f389", "reaction_type": "unicode_emoji", "id": 0, } - type: object additionalProperties: false description: | Event sent to a user's clients when the user uploads a new file in a Zulip message. Useful to implement live update in UI showing all files the current user has uploaded. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - attachment op: type: string enum: - add attachment: $ref: "#/components/schemas/Attachments" upload_space_used: type: integer description: | The total size of all files uploaded by in the organization, in bytes. example: { "type": "attachment", "op": "add", "attachment": { "id": 1, "name": "zulip.txt", "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", "size": 6, "create_time": 1594825414000, "messages": [], }, "upload_space_used": 6, "id": 0, } - type: object additionalProperties: false description: | Event sent to a user's clients when details of a file that user uploaded are changed. Most updates will be changes in the list of messages that reference the uploaded file. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - attachment op: type: string enum: - update attachment: $ref: "#/components/schemas/Attachments" upload_space_used: type: integer description: | The total size of all files uploaded by in the organization, in bytes. example: { "type": "attachment", "op": "update", "attachment": { "id": 1, "name": "zulip.txt", "path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt", "size": 6, "create_time": 1594825414000, "messages": [], }, "upload_space_used": 6, "id": 0, } - type: object additionalProperties: false description: | Event sent to a user's clients when the user deletes a file they had uploaded. Useful primarily for UI showing all the files the current user has uploaded. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - attachment op: type: string enum: - remove attachment: type: object description: | Dictionary containing the ID of the deleted attachment. additionalProperties: false properties: id: type: integer description: | The ID of the deleted attachment. upload_space_used: type: integer description: | The total size of all files uploaded by in the organization, in bytes. example: { "type": "attachment", "op": "remove", "attachment": {"id": 1}, "upload_space_used": 0, "id": 0, } - type: object additionalProperties: false description: | Event sent when a submessage is added to a message. Submessages are an **experimental** API used for widgets such as the `/poll` widget in Zulip. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - submessage msg_type: type: string description: | The type of the message. content: type: string description: | The new content of the submessage. message_id: type: integer description: | The ID of the message to which the submessage has been added. sender_id: type: integer description: | The ID of the user who sent the message. submessage_id: type: integer description: | The ID of the submessage. example: { "type": "submessage", "msg_type": "widget", "message_id": 970461, "submessage_id": 4737, "sender_id": 58, "content": '{"type":"vote","key":"58,1","vote":1}', "id": 28, } - type: object additionalProperties: false description: | Event sent to all users who can access the modified user when the status of a user changes. **Changes**: Prior to Zulip 8.0 (feature level 228), this event was sent to all users in the organization. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_status away: type: boolean deprecated: true description: | Whether the user has marked themself "away" with this status. **Changes**: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, `away` is a legacy way to access the user's `presence_enabled` setting, with `away = !presence_enabled`. To be removed in a future release. status_text: type: string description: | The text content of the status message. This will be `""` for users who set a status without selecting or writing a message. emoji_name: type: string description: | The [emoji name](/api/update-status#parameter-emoji_name) for the emoji the user selected for their new status. This will be `""` for users who set a status without selecting an emoji. **Changes**: New in Zulip 5.0 (feature level 86). emoji_code: type: string description: | The [emoji code](/api/update-status#parameter-emoji_code) for the emoji the user selected for their new status. This will be `""` for users who set a status without selecting an emoji. **Changes**: New in Zulip 5.0 (feature level 86). reaction_type: type: string enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: | The [emoji type](/api/update-status#parameter-reaction_type) for the emoji the user selected for their new status. This will be `""` for users who set a status without selecting an emoji. **Changes**: New in Zulip 5.0 (feature level 86). user_id: type: integer description: | The ID of the user whose status changed. example: { "type": "user_status", "user_id": 10, "away": true, "status_text": "out to lunch", "emoji_name": "car", "emoji_code": "1f697", "reaction_type": "unicode_emoji", "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when new custom profile field types are configured for that Zulip organization. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - custom_profile_fields fields: type: array description: | An array of dictionaries where each dictionary contains details of a single new custom profile field for the Zulip organization. items: $ref: "#/components/schemas/CustomProfileField" example: { "type": "custom_profile_fields", "fields": [ { "id": 1, "name": "Phone number", "type": 1, "hint": "", "field_data": "", "order": 1, "required": true, "editable_by_user": true, }, { "id": 2, "name": "Biography", "type": 2, "hint": "What are you known for?", "field_data": "", "order": 2, "required": true, "editable_by_user": true, }, { "id": 3, "name": "Favorite food", "type": 1, "hint": "Or drink, if you'd prefer", "field_data": "", "order": 3, "required": false, "editable_by_user": true, }, { "id": 4, "name": "Favorite editor", "type": 3, "hint": "", "field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}', "order": 4, "display_in_profile_summary": true, "required": true, "editable_by_user": true, }, { "id": 5, "name": "Birthday", "type": 4, "hint": "", "field_data": "", "order": 5, "required": false, "editable_by_user": false, }, { "id": 6, "name": "Favorite website", "type": 5, "hint": "Or your personal blog's URL", "field_data": "", "order": 6, "display_in_profile_summary": true, "required": false, "editable_by_user": true, }, { "id": 7, "name": "Mentor", "type": 6, "hint": "", "field_data": "", "order": 7, "required": true, "editable_by_user": false, }, { "id": 8, "name": "GitHub", "type": 7, "hint": "Enter your GitHub username", "field_data": '{"subtype":"github"}', "order": 8, "required": true, "editable_by_user": true, }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when an organization administrator changes the organization's configured default channel groups. Default channel groups are an **experimental** feature that is not yet stabilized. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - default_stream_groups default_stream_groups: type: array description: | An array of dictionaries where each dictionary contains details about a single default channel group. items: $ref: "#/components/schemas/DefaultChannelGroup" example: { "type": "default_stream_groups", "default_stream_groups": [ { "name": "group1", "id": 2, "description": "New description", "streams": [ { "name": "Scotland", "stream_id": 3, "description": "Located in the United Kingdom", "rendered_description": "Located in the United Kingdom
", "date_created": 1691057093, "creator_id": 8, "invite_only": false, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": true, "first_message_id": 1, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, }, { "name": "Denmark", "stream_id": 1, "description": "A Scandinavian country", "rendered_description": "A Scandinavian country
", "date_created": 1691057093, "creator_id": null, "invite_only": false, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": true, "first_message_id": 4, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, }, { "name": "Verona", "stream_id": 5, "description": "A city in Italy", "rendered_description": "A city in Italy
", "date_created": 1691057093, "creator_id": 9, "invite_only": false, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": true, "first_message_id": 6, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, }, ], }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when the default channels in the organization are changed by an organization administrator. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - default_streams default_streams: type: array description: | An array of dictionaries where each dictionary contains details about a single default channel. items: $ref: "#/components/schemas/DefaultChannel" example: { "type": "default_streams", "default_streams": [ { "name": "Scotland", "stream_id": 3, "description": "Located in the United Kingdom", "rendered_description": "Located in the United Kingdom
", "date_created": 1691057093, "creator_id": 8, "invite_only": false, "is_web_public": false, "stream_post_policy": 1, "history_public_to_subscribers": true, "first_message_id": 1, "message_retention_days": null, "is_announcement_only": false, "can_remove_subscribers_group": 2, }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a message has been deleted. Sent to all users who currently are subscribed to the messages' recipient. May also be sent to additional users who had access to it, including, in particular, an administrator user deleting messages in a stream that they are not subscribed to. This means that clients can assume that they will always receive an event of this type for deletions that the client itself initiated. This event is also sent when the user loses access to a message, such as when it is [moved to a channel][message-move-channel] that the user does not [have permission to access][channel-access]. **Changes**: Before Zulip 9.0 (feature level 274), this event was only sent to subscribers of the message's recipient. Before Zulip 5.0 (feature level 77), events for direct messages contained additional `sender_id` and `recipient_id` fields. [message-move-channel]: /help/move-content-to-another-channel [channel-access]: /help/channel-permissions properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - delete_message message_ids: type: array description: | Only present for clients that support the `bulk_message_deletion` [client capability][client-capabilities]. A list containing the IDs of the newly deleted messages. [client-capabilities]: /api/register-queue#parameter-client_capabilities items: type: integer message_id: type: integer description: | Only present for clients that do not support the `bulk_message_deletion` [client capability][client-capabilities]. The ID of the newly deleted message. [client-capabilities]: /api/register-queue#parameter-client_capabilities message_type: type: string description: | The type of message. Either `"stream"` or `"private"`. enum: - private - stream stream_id: type: integer description: | Only present if `message_type` is `"stream"`. The ID of the channel to which the message was sent. topic: type: string description: | Only present if `message_type` is `"stream"`. The topic to which the message was sent. example: { "type": "delete_message", "message_type": "private", "message_id": 37, "id": 0, } - type: object description: | Event sent to a user's clients when that user's set of configured muted topics have changed. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - muted_topics muted_topics: type: array deprecated: true description: | Array of tuples, where each tuple describes a muted topic. The first element of the tuple is the channel name in which the topic has to be muted, the second element is the topic name to be muted and the third element is an integer UNIX timestamp representing when the topic was muted. **Changes**: Deprecated in Zulip 6.0 (feature level 134). Starting with this version, clients that explicitly requested the replacement `user_topic` event type when registering their event queue will not receive this legacy event type. Before Zulip 3.0 (feature level 1), the `muted_topics` array objects were 2-item tuples and did not include the timestamp information for when the topic was muted. items: type: array items: oneOf: - type: string - type: integer additionalProperties: false example: { "type": "muted_topics", "muted_topics": [["Denmark", "topic", 1594825442]], "id": 0, } - type: object description: | Event sent to a user's clients when the user mutes/unmutes a topic, or otherwise modifies their personal per-topic configuration. **Changes**: New in Zulip 6.0 (feature level 134). Previously, clients were notified about changes in muted topic configuration via the `muted_topics` event type. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_topic stream_id: type: integer description: | The ID of the channel to which the topic belongs. topic_name: type: string description: | The name of the topic. last_updated: type: integer description: | An integer UNIX timestamp representing when the user-topic relationship was last changed. visibility_policy: type: integer description: | An integer indicating the user's visibility preferences for the topic, such as whether the topic is muted. - 0 = None. Used to indicate that the user no longer has a special visibility policy for this topic. - 1 = Muted. Used to record [muted topics](/help/mute-a-topic). - 2 = Unmuted. Used to record unmuted topics. - 3 = Followed. Used to record [followed topics](/help/follow-a-topic). **Changes**: In Zulip 7.0 (feature level 219), added followed as a visibility policy option. In Zulip 7.0 (feature level 170), added unmuted as a visibility policy option. additionalProperties: false example: { "id": 1, "type": "user_topic", "stream_id": 1, "topic_name": "topic", "last_updated": 1594825442, "visibility_policy": 1, } - type: object description: | Event sent to a user's clients when that user's set of configured [muted users](/api/mute-user) have changed. **Changes**: New in Zulip 4.0 (feature level 48). properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - muted_users muted_users: type: array description: | A list of dictionaries where each dictionary describes a muted user. items: type: object additionalProperties: false description: | Object containing the user ID and timestamp of a muted user. properties: id: type: integer description: | The ID of the muted user. timestamp: type: integer description: | An integer UNIX timestamp representing when the user was muted. additionalProperties: false example: { "type": "muted_users", "muted_users": [ {"id": 1, "timestamp": 1594825442}, {"id": 22, "timestamp": 1654865392}, ], "id": 0, } - type: object additionalProperties: false description: | Heartbeat events are sent by the server to avoid longpolling connections being affected by networks that kill idle HTTP connections. Clients do not need to do anything to process these events, beyond the common `last_event_id` accounting. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - heartbeat example: {"type": "heartbeat", "id": 0} - type: object additionalProperties: false description: | Event sent when the set of onboarding steps to show for the current user has changed (e.g. because the user dismissed one). Clients that feature a similar tutorial experience to the Zulip web app may want to handle these events. **Changes**: Before Zulip 8.0 (feature level 233), this event was named `hotspots`. Prior to this feature level, one-time notice onboarding steps were not supported. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - onboarding_steps onboarding_steps: type: array description: | An array of dictionaries where each dictionary contains details about a single onboarding step. **Changes**: Before Zulip 8.0 (feature level 233), this array was named `hotspots`. Prior to this feature level, one-time notice onboarding steps were not supported, and the `type` field in these objects did not exist as all onboarding steps were implicitly hotspots. items: $ref: "#/components/schemas/OnboardingStep" example: { "type": "onboarding_steps", "onboarding_steps": [ { "type": "one_time_notice", "name": "visibility_policy_banner", }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a message's content, topic and/or channel has been edited or when a message's content has a rendering update, such as for an [inline URL preview][inline-url-previews]. Sent to all users who had received the original message. [inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews **Changes**: In Zulip 10.0 (feature level 284), removed the `prev_rendered_content_version` field as it is an internal server implementation detail not used by any client. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - update_message user_id: type: integer nullable: true description: | The ID of the user who sent the message. Is `null` when event is for a rendering update of the original message, such as for an [inline URL preview][inline-url-previews]. **Changes**: As of Zulip 5.0 (feature level 114), this field is present for all `update_message` events. Previously, this field was omitted for [inline URL preview][inline-url-previews] updates. rendering_only: type: boolean description: | Whether the event only updates the rendered content of the message. This field should be used by clients to determine if the event only provides a rendering update to the message content, such as for an [inline URL preview][inline-url-previews]. When `true`, the event does not reflect a user-generated edit and does not modify the message history. **Changes**: New in Zulip 5.0 (feature level 114). Clients can correctly identify these rendering update event with earlier Zulip versions by checking whether the `user_id` field was omitted. message_id: type: integer description: | The ID of the message which was edited or updated. This field should be used to apply content edits to the client's cached message history, or to apply rendered content updates. If the channel or topic was changed, the set of moved messages is encoded in the separate `message_ids` field, which is guaranteed to include `message_id`. message_ids: type: array items: type: integer description: | The list of IDs of messages to which any channel or topic changes encoded in this event should be applied. This list always includes `message_id`, even when there are no channel or topic changes to apply. These messages are guaranteed to have all been previously sent to channel `stream_id` with topic `orig_subject`, and have been moved to `new_stream_id` with topic `subject` (if those fields are present in the event). Clients processing these events should update all cached message history associated with the moved messages (including adjusting `unread_msgs` data structures, where the client may not have the message itself in its history) to reflect the new channel and topic. Content changes should be applied only to the single message indicated by `message_id`. flags: type: array description: | The user's personal [message flags][message-flags] for the message with ID `message_id` following the edit. A client application should compare these to the original flags to identify cases where a mention or alert word was added by the edit. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level. [message-flags]: /api/update-message-flags#available-flags items: type: string edit_timestamp: type: integer description: | The time when this message edit operation was processed by the server. **Changes**: As of Zulip 5.0 (feature level 114), this field is present for all `update_message` events. Previously, this field was omitted for [inline URL preview][inline-url-previews] updates. stream_name: type: string description: | Only present if the message was edited and originally sent to a channel. The name of the channel that the message was sent to. Clients are recommended to use the `stream_id` field instead. stream_id: type: integer description: | Only present if the message was edited and originally sent to a channel. The pre-edit channel for all of the messages with IDs in `message_ids`. **Changes**: As of Zulip 5.0 (feature level 112), this field is present for all edits to a channel message. Previously, it was not present when only the content of the channel message was edited. new_stream_id: type: integer description: | Only present if message(s) were moved to a different channel. The post-edit channel for all of the messages with IDs in `message_ids`. propagate_mode: type: string description: | Only present if this event moved messages to a different topic and/or channel. The choice the editing user made about which messages should be affected by a channel/topic edit: - `"change_one"`: Just change the one indicated in `message_id`. - `"change_later"`: Change messages in the same topic that had been sent after this one. - `"change_all"`: Change all messages in that topic. This parameter should be used to decide whether to change navigation and compose box state in response to the edit. For example, if the user was previously in topic narrow, and the topic was edited with `"change_later"` or `"change_all"`, the Zulip web app will automatically navigate to the new topic narrow. Similarly, a message being composed to the old topic should have its recipient changed to the new topic. This navigation makes it much more convenient to move content between topics without disruption or messages continuing to be sent to the pre-edit topic by accident. enum: - change_one - change_later - change_all orig_subject: type: string description: | Only present if this event moved messages to a different topic and/or channel. The pre-edit topic for all of the messages with IDs in `message_ids`. subject: type: string description: | Only present if this event moved messages to a different topic; this field will not be present when moving messages to the same topic name in a different channel. The post-edit topic for all of the messages with IDs in `message_ids`. topic_links: type: array items: type: object additionalProperties: false properties: text: type: string description: | The original link text present in the topic. url: type: string description: | The expanded target url which the link points to. description: | Only present if this event moved messages to a different topic; this field will not be present when moving messages to the same topic name in a different channel. Data on any links to be included in the `topic` line (these are generated by [custom linkification filter](/help/add-a-custom-linkifier) that match content in the message's topic.), corresponding to the post-edit topic. **Changes**: This field contained a list of urls before Zulip 4.0 (feature level 46). New in Zulip 3.0 (feature level 1). Previously, this field was called `subject_links`; clients are recommended to rename `subject_links` to `topic_links` if present for compatibility with older Zulip servers. orig_content: type: string description: | Only present if this event changed the message content. The original content of the message with ID `message_id` immediately prior to this edit, in the original markdown. orig_rendered_content: type: string description: | Only present if this event changed the message content. The original content of the message with ID `message_id` immediately prior to this edit, rendered as HTML. 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": "hello
", "content": "new content", "rendered_content": "new content
", "is_me_message": false, "propagate_mode": "change_all", "stream_id": 5, "orig_subject": "test", "subject": "new_topic", "topic_links": [], "message_ids": [58, 57], "flags": [], "rendering_only": false, "id": 0, } - type: object additionalProperties: false description: | Event sent when a user starts typing a message. Sent to all clients for users who would receive the message being typed, with the additional rule that typing notifications for channel messages are only sent to clients that included `stream_typing_notifications` in their [client capabilities][client-capabilities] when registering the event queue. See [POST /typing](/api/set-typing-status) endpoint for more details. **Changes**: Typing notifications for channel messages are new in Zulip 4.0 (feature level 58). [client-capabilities]: /api/register-queue#parameter-client_capabilities properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - typing op: type: string enum: - start message_type: type: string description: | Type of message being composed. Must be `"stream"` or `"direct"`. **Changes**: In Zulip 8.0 (feature level 215), replaced the value `"private"` with `"direct"`. New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly direct messages. enum: - direct - stream sender: additionalProperties: false type: object description: | Object describing the user who is typing the message. properties: user_id: type: integer description: | The user's ID. email: type: string description: | The Zulip API email address for the user. recipients: type: array description: | Only present if `message_type` is `"direct"`. Array of dictionaries describing the set of users who would be recipients of the message being typed. Each dictionary contains details about one of the recipients. The sending user is guaranteed to appear among the recipients. items: type: object additionalProperties: false description: | Object containing the user ID and Zulip API email of a recipient. properties: user_id: type: integer description: | The ID of the user. email: type: string description: | The Zulip API email address for the user. stream_id: type: integer description: | Only present if `message_type` is `"stream"`. The unique ID of the channel to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. topic: type: string description: | Only present if `message_type` is `"stream"`. Topic within the channel where the message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. example: { "type": "typing", "op": "start", "message_type": "direct", "sender": { "user_id": 10, "email": "user10@zulip.testserver", }, "recipients": [ { "user_id": 8, "email": "user8@zulip.testserver", }, { "user_id": 10, "email": "user10@zulip.testserver", }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a user stops typing a message. Sent to all clients for users who would receive the message that was previously being typed, with the additional rule that typing notifications for channel messages are only sent to clients that included `stream_typing_notifications` in their [client capabilities][client-capabilities] when registering the event queue. See [POST /typing](/api/set-typing-status) endpoint for more details. **Changes**: Typing notifications for channel messages are new in Zulip 4.0 (feature level 58). [client-capabilities]: /api/register-queue#parameter-client_capabilities properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - typing op: type: string enum: - stop message_type: type: string description: | Type of message being composed. Must be `"stream"` or `"direct"`. **Changes**: In Zulip 8.0 (feature level 215), replaced the value `"private"` with `"direct"`. New in Zulip 4.0 (feature level 58). Previously all typing notifications were implicitly direct messages. enum: - direct - stream sender: additionalProperties: false type: object description: | Object describing the user who was previously typing the message. properties: user_id: type: integer description: | The user's ID. email: type: string description: | The Zulip API email address for the user. recipients: type: array description: | Only present if `message_type` is `"direct"`. Array of dictionaries describing the set of users who would be recipients of the message that was previously being typed. Each dictionary contains details about one of the recipients. The sending user is guaranteed to appear among the recipients. items: type: object additionalProperties: false description: | Object containing the user ID and email of a recipient. properties: user_id: type: integer description: | The ID of the user. email: type: string description: | The Zulip API email address for the user. stream_id: type: integer description: | Only present if `message_type` is `"stream"`. The unique ID of the channel to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. topic: type: string description: | Only present if `message_type` is `"stream"`. Topic within the channel where the message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. example: { "type": "typing", "op": "stop", "message_type": "direct", "sender": { "user_id": 10, "email": "user10@zulip.testserver", }, "recipients": [ { "user_id": 8, "email": "user8@zulip.testserver", }, { "user_id": 10, "email": "user10@zulip.testserver", }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent to a user when [message flags][message-flags] are added to messages. This can reflect a direct user action, or can be the indirect consequence of another action. Whatever the cause, if there's a change in the set of message flags that the user has for a message, then an `update_message_flags` event will be sent with the change. Note that this applies when the user already had access to the message, and continues to have access to it. When a message newly appears or disappears, a [`message`][message-event] or [`delete_message`][message-delete] event is sent instead. Some examples of actions that trigger an `update_message_flags` event: - The `"starred"` flag is added when the user chooses to [star a message](/help/star-a-message). - The `"read"` flag is added when the user marks messages as read by scrolling through them, or uses [Mark all messages as read][all-read] on a conversation. - The `"read"` flag is added when the user [mutes](/help/mute-a-user) a message's sender. - The `"read"` flag is added after the user unsubscribes from a channel, or messages are moved to a not-subscribed channel, provided the user can still access the messages at all. Note a [`delete_message`][message-delete] event is sent in the case where the user can no longer access the messages. In some cases, a change in message flags that's caused by another change may happen a short while after the original change, rather than simultaneously. For example, when messages that were unread are moved to a channel where the user is not subscribed, the resulting change in message flags (and the corresponding `update_message_flags` event with flag `"read"`) may happen later than the message move itself. The delay in that example is typically at most a few hundred milliseconds and can in rare cases be minutes or longer. [message-flags]: /api/update-message-flags#available-flags [message-event]: /api/get-events#message [message-delete]: /api/get-events#delete_message [all-read]: /help/marking-messages-as-read#mark-all-messages-as-read properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - update_message_flags op: type: string enum: - add operation: deprecated: true description: | Old name for the `op` field in this event type. **Deprecated** in Zulip 4.0 (feature level 32), and replaced by the `op` field. type: string enum: - add flag: type: string description: | The [flag][message-flags] that was added. messages: type: array description: | Array containing the IDs of all messages to which the flag was added. items: type: integer all: type: boolean description: | Whether the specified flag was added to all messages. This field is only relevant for the `"read"` flag, and will be `false` for all other flags. When `true` for the `"read"` flag, then the `messages` array will be empty. example: { "type": "update_message_flags", "op": "add", "operation": "add", "flag": "starred", "messages": [63], "all": false, "id": 0, } - type: object additionalProperties: false description: | Event sent to a user when [message flags][message-flags] are removed from messages. See the description for the [`update_message_flags` op: `add`](/api/get-events#update_message_flags-add) event for more details about these events. [message-flags]: /api/update-message-flags#available-flags properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - update_message_flags op: type: string enum: - remove operation: deprecated: true type: string description: | Old name for the `op` field in this event type. **Deprecated** in Zulip 4.0 (feature level 32), and replaced by the `op` field. enum: - remove flag: type: string description: | The [flag][message-flags] to be removed. messages: type: array description: | Array containing the IDs of the messages from which the flag was removed. items: type: integer all: deprecated: true type: boolean description: | Will be `false` for all specified flags. **Deprecated** and will be removed in a future release. message_details: description: | Only present if the specified `flag` is `"read"`. A set of data structures describing the messages that are being marked as unread with additional details to allow clients to update the `unread_msgs` data structure for these messages (which may not be otherwise known to the client). **Changes**: New in Zulip 5.0 (feature level 121). Previously, marking already read messages as unread was not supported by the Zulip API. type: object additionalProperties: type: object description: | `{message_id}`: Object containing details about the message with the specified ID. additionalProperties: false required: ["type"] properties: type: type: string description: | The type of this message. Either `"stream"` or `"private"`. enum: - private - stream mentioned: type: boolean description: | A flag which indicates whether the message contains a mention of the user. Present only if the message mentions the current user. user_ids: type: array items: type: integer description: | Present only if `type` is `private`. The user IDs of every recipient of this direct message, excluding yourself. Will be the empty list for a message you had sent to only yourself. stream_id: type: integer description: | Present only if `type` is `"stream"`. The ID of the channel where the message was sent. topic: type: string description: | Present only if `type` is `"stream"`. Name of the topic where the message was sent. unmuted_stream_msg: type: boolean deprecated: true description: | **Deprecated** internal implementation detail. Clients should ignore this field as it will be removed in the future. example: { "type": "update_message_flags", "op": "remove", "operation": "remove", "flag": "starred", "messages": [63], "message_details": { "63": { "type": "stream", "stream_id": 22, "topic": "lunch", }, }, "all": false, "id": 0, } - type: object additionalProperties: false description: | Event sent to users in an organization when a [user group](/help/user-groups) is created. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - add group: $ref: "#/components/schemas/UserGroup" example: { "type": "user_group", "op": "add", "group": { "name": "backend", "members": [12], "creator_id": 9, "date_created": 1717484476, "description": "Backend team", "id": 2, "is_system_group": false, "can_add_members_group": 16, "can_join_group": 16, "can_leave_group": 15, "can_manage_group": 16, "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. For group deactivation, this event is only sent if `include_deactivated_groups` client capability is set to `true`. This event is also sent when deactivating or reactivating a user for settings set to anonymous user groups which the user is direct member of. When deactivating the user, event is only sent to users who cannot access the deactivated user. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when deactivating or reactivating a user. Prior to Zulip 10.0 (feature level 294), this event was sent to all clients when a user group was deactivated. 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_add_members_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to add members to this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values can_join_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to join this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values can_leave_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to leave this group. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values can_manage_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [manage this group][manage-user-groups]. Only present if this user group permission setting changed. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups can_mention_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. Only present if this user group permission setting changed. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group deactivated: type: boolean description: | Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). 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. This event is also sent when reactivating a user for all the user groups the reactivated user was a member of before being deactivated. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when reactivating a user. 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. This event is also sent when deactivating a user, for all the user groups the deactivated user is a member of, but only to the users who cannot access the deactivated user. **Changes**: Starting with Zulip 10.0 (feature level 303), this event can also be sent when deactivating a user. 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 when a user group is deactivated but only to clients with `include_deactivated_groups` client capability set to `false`. **Changes**: Prior to Zulip 10.0 (feature level 294), this event was sent when a user group was 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": "#(?PHello there!
", "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": "Hello there!
", "scheduled_delivery_timestamp": 1681662420, "failed": false, }, } - type: object additionalProperties: false description: | Event sent to a user's clients when a scheduled message is deleted. **Changes**: New in Zulip 7.0 (feature level 179). properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - scheduled_messages op: type: string enum: - remove scheduled_message_id: type: integer description: | The ID of the scheduled message that was deleted. example: { "type": "scheduled_messages", "op": "remove", "scheduled_message_id": 17, } queue_id: type: string description: | The ID of the registered queue. example: { "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", "events": [ { "id": 0, "message": { "avatar_url": "https://url/for/othello-bots/avatar", "client": "website", "content": "I come not, friends, to steal away your hearts.", "content_type": "text/x-markdown", "display_recipient": "Denmark", "id": 12345678, "recipient_id": 12314, "sender_email": "othello-bot@example.com", "sender_full_name": "Othello Bot", "sender_id": 13215, "sender_realm_str": "example", "topic_links": [], "timestamp": 1375978403, "type": "stream", }, "type": "message", }, { "id": 1, "message": { "avatar_url": "https://url/for/othello-bots/avatar", "client": "website", "content": "With mirth and laughter let old wrinkles come.", "content_type": "text/x-markdown", "display_recipient": [ { "email": "hamlet@example.com", "full_name": "Hamlet of Denmark", "id": 31572, }, ], "id": 12345679, "recipient_id": 18391, "sender_email": "othello-bot@example.com", "sender_full_name": "Othello Bot", "sender_id": 13215, "sender_realm_str": "example", "subject": "", "topic_links": [], "timestamp": 1375978404, "type": "private", }, "type": "message", }, ], "msg": "", "result": "success", } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/BadEventQueueIdError" - description: | #### BAD_EVENT_QUEUE_ID errors This error occurs if the target event queue has been garbage collected. A compliant client will handle this error by re-initializing itself (e.g. a Zulip web app browser window will reload in this case). See [the /register endpoint docs](/api/register-queue) for details on how to handle these correctly. The following is the error response in such case: delete: operationId: delete-queue summary: Delete an event queue tags: ["real_time_events"] description: | Delete a previously registered queue. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: queue_id: description: | The ID of an event queue that was previously registered via `POST /api/v1/register` (see [Register a queue](/api/register-queue)). type: string example: fb67bf8a-c031-47cc-84cf-ed80accacda8 required: - queue_id responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/BadEventQueueIdError" - description: | A typical JSON response for when the `queue_id` is non-existent or the associated queue has already been deleted: /get_stream_id: get: operationId: get-stream-id summary: Get channel ID tags: ["channels"] description: | Get the unique ID of a given channel. parameters: - name: stream in: query description: | The name of the channel to access. schema: type: string example: Denmark required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} stream_id: type: integer description: | The ID of the given channel. example: {"msg": "", "result": "success", "stream_id": 15} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid channel name 'nonexistent'", "result": "error", } description: | An example JSON response for when the supplied channel does not exist: /mark_all_as_read: post: deprecated: true operationId: mark-all-as-read summary: Mark all messages as read tags: ["messages"] description: | Marks all of the current user's unread messages as read. Because this endpoint marks messages as read in batches, it is possible for the request to time out after only marking some messages as read. When this happens, the `complete` boolean field in the success response will be `false`. Clients should repeat the request when handling such a response. If all messages were marked as read, then the success response will return `"complete": true`. **Changes**: Deprecated; clients should use the [update personal message flags for narrow](/api/update-message-flags-for-narrow) endpoint instead as this endpoint will be removed in a future release. Before Zulip 8.0 (feature level 211), if the server's processing was interrupted by a timeout, but some messages were marked as read, then it would return `"result": "partially_completed"`, along with a `code` field for an error string, in the success response to indicate that there was a timeout and that the client should repeat the request. Before Zulip 6.0 (feature level 153), this request did a single atomic operation, which could time out with 10,000s of unread messages to mark as read. As of this feature level, messages are marked as read in batches, starting with the newest messages, so that progress is made even if the request times out. And, instead of returning an error when the request times out and some messages have been marked as read, a success response with `"result": "partially_completed"` is returned. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false required: - complete properties: result: {} msg: {} ignored_parameters_unsupported: {} complete: type: boolean description: | Whether all unread messages were marked as read. Will be `false` if the request successfully marked some, but not all, messages as read. example: {"msg": "", "result": "success", "complete": true} /mark_stream_as_read: post: deprecated: true operationId: mark-stream-as-read summary: Mark messages in a channel as read tags: ["messages"] description: | Mark all the unread messages in a channel as read. **Changes**: Deprecated; clients should use the [update personal message flags for narrow](/api/update-message-flags-for-narrow) endpoint instead as this endpoint will be removed in a future release. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the channel to access. type: integer example: 43 required: - stream_id encoding: stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" /mark_topic_as_read: post: deprecated: true operationId: mark-topic-as-read summary: Mark messages in a topic as read tags: ["messages"] description: | Mark all the unread messages in a topic as read. **Changes**: Deprecated; clients should use the [update personal message flags for narrow](/api/update-message-flags-for-narrow) endpoint instead as this endpoint will be removed in a future release. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the channel to access. type: integer example: 43 topic_name: description: | The name of the topic whose messages should be marked as read. type: string example: new coffee machine required: - stream_id - topic_name encoding: stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" /attachments: get: operationId: get-attachments summary: Get attachments tags: ["users"] description: | Fetch metadata on files uploaded by the requesting user. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} attachments: type: array description: | A list of `attachment` objects, each containing details about a file uploaded by the user. items: $ref: "#/components/schemas/Attachments" upload_space_used: type: integer description: | The total size of all files uploaded by users in the organization, in bytes. example: { "result": "success", "msg": "", "attachments": [ { "id": 1, "name": "166050.jpg", "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg", "size": 571946, "create_time": 1588145417000, "messages": [ {"id": 102, "date_sent": 1588145424000}, {"id": 103, "date_sent": 1588145448000}, ], }, ], "upload_space_used": 571946, } /attachments/{attachment_id}: delete: operationId: remove-attachment summary: Delete an attachment tags: ["users"] description: | Delete an uploaded file given its attachment ID. Note that uploaded files that have been referenced in at least one message are automatically deleted once the last message containing a link to them is deleted (whether directly or via a [message retention policy](/help/message-retention-policy)). Uploaded files that are never used in a message are automatically deleted a few weeks after being uploaded. Attachment IDs can be contained from [GET /attachments](/api/get-attachments). parameters: - name: attachment_id in: path description: | The ID of the attachment to be deleted. schema: type: integer example: 1 required: true responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid attachment", "code": "BAD_REQUEST", } description: | A typical failed JSON response for when the `attachment_id` is invalid "401": description: Error. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "UNAUTHORIZED", "result": "error", "msg": "Not logged in: API authentication or user session required", } description: | A typical failed JSON response for when the user is not logged in: /drafts: get: operationId: get-drafts tags: ["drafts"] summary: Get drafts description: | Fetch all drafts for the current user. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} count: type: integer description: | The number of drafts the user currently has. Also the number of drafts returned under "drafts". example: 3 drafts: type: array description: | Returns all of the current user's drafts, in order of last edit time (with the most recently edited draft appearing first). items: $ref: "#/components/schemas/Draft" example: { "result": "success", "msg": "", "count": 3, "drafts": [ { "id": 1, "type": "stream", "to": [3], "topic": "sync drafts", "content": "Let's add backend support for syncing drafts.", "timestamp": 1595479019, }, { "id": 2, "type": "private", "to": [4], "topic": "", "content": "What if we made it possible to sync drafts in Zulip?", "timestamp": 1595479019, }, { "id": 3, "type": "private", "to": [4, 10], "topic": "", "content": "What if we made it possible to sync drafts in Zulip?", "timestamp": 1595479019, }, ], } post: operationId: create-drafts tags: ["drafts"] summary: Create drafts description: | Create one or more drafts on the server. These drafts will be automatically synchronized to other clients via `drafts` events. requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: drafts: description: | A JSON-encoded list of containing new draft objects. type: array items: $ref: "#/components/schemas/Draft" example: [ { "type": "stream", "to": [1], "topic": "questions", "content": "What are the contribution guidelines for this project?", "timestamp": 1595479019, }, ] encoding: drafts: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} ids: type: array description: | An array of the IDs for the drafts that were just created in the same order as they were submitted. items: type: integer example: {"result": "success", "msg": "", "ids": [1, 2, 3]} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | JSON response for when a draft targeted towards a channel does not specify exactly one channel ID: example: { "code": "BAD_REQUEST", "msg": "Must specify exactly 1 channel ID for channel messages", "result": "error", } /drafts/{draft_id}: patch: operationId: edit-draft tags: ["drafts"] summary: Edit a draft description: | Edit a draft on the server. The edit will be automatically synchronized to other clients via `drafts` events. parameters: - name: draft_id in: path schema: type: integer description: | The ID of the draft to be edited. required: true example: 2 requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: draft: allOf: - $ref: "#/components/schemas/Draft" - description: | A JSON-encoded object containing a replacement draft object for this ID. example: { "type": "stream", "to": [1], "topic": "questions", "content": "how tough is a Lamy Safari?", "timestamp": 1595479019, } required: - draft encoding: draft: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "404": description: Not Found. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when no draft exists with the provided ID: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Draft does not exist", } delete: operationId: delete-draft tags: ["drafts"] summary: Delete a draft description: | Delete a single draft from the server. The deletion will be automatically synchronized to other clients via a `drafts` event. parameters: - name: draft_id in: path schema: type: integer description: | The ID of the draft you want to delete. required: true example: 1 responses: "200": $ref: "#/components/responses/SimpleSuccess" "404": description: Not Found. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when no draft exists with the provided ID: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Draft does not exist", } /saved_snippets: get: operationId: get-saved-snippets tags: ["drafts"] summary: Get all saved snippets description: | Fetch all the saved snippets for the current user. **Changes**: New in Zulip 10.0 (feature level 297). responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} saved_snippets: type: array description: | An array of dictionaries containing data on all of the current user's saved snippets. items: $ref: "#/components/schemas/SavedSnippet" example: { "result": "success", "msg": "", "saved_snippets": [ { "id": 1, "title": "Example", "content": "Welcome to the organization.", "date_created": 1681662420, }, ], } post: operationId: create-saved-snippet tags: ["drafts"] summary: Create a saved snippet description: | Create a new saved snippet for the current user. **Changes**: New in Zulip 10.0 (feature level 297). requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: title: type: string description: | The title of the saved snippet. example: Example title content: type: string description: | The content of the saved snippet in text/markdown format. Clients should insert this content into a message when using a saved snippet. example: Welcome to the organization. required: - title - content responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} saved_snippet_id: type: integer description: | The unique ID of the saved snippet created. example: {"result": "success", "msg": "", "saved_snippet_id": 1} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Title cannot be empty.", "result": "error", } description: | A typical failed JSON response for when either title or content is empty: /saved_snippets/{saved_snippet_id}: delete: operationId: delete-saved-snippet tags: ["drafts"] summary: Delete a saved snippet description: | Delete a saved snippet. **Changes**: New in Zulip 10.0 (feature level 297). parameters: - name: saved_snippet_id in: path schema: type: integer description: | The ID of the saved snippet to delete. required: true example: 2 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 saved snippet exists with the provided ID: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Saved snippet 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": "Hi
", "topic": "Introduction", "scheduled_delivery_timestamp": 1681662420, "failed": false, }, ], } post: operationId: create-scheduled-message tags: ["scheduled_messages"] summary: Create a scheduled message description: | Create a new [scheduled message](/help/schedule-a-message). **Changes**: In Zulip 7.0 (feature level 184), moved support for [editing a scheduled message](/api/update-scheduled-message) to a separate API endpoint, which removed the `scheduled_message_id` parameter from this endpoint. New in Zulip 7.0 (feature level 179). requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: type: description: | The type of scheduled message to be sent. `"direct"` for a direct message and `"stream"` or `"channel"` for a channel message. Note that, while `"private"` is supported for scheduling direct messages, clients are encouraged to use to the modern convention of `"direct"` to indicate this message type, because support for `"private"` may eventually be removed. **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as an additional value for this parameter to indicate the type of a channel message. type: string enum: - direct - channel - stream - private example: direct to: description: | The scheduled message's tentative target audience. For channel messages, the integer ID of the channel. For direct messages, a list containing integer user IDs. oneOf: - type: integer - type: array items: type: integer minLength: 1 example: [9, 10] content: $ref: "#/components/schemas/RequiredContent" topic: description: | The topic of the message. Only required for channel messages (`"type": "stream"` or `"type": "channel"`), ignored otherwise. Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length. type: string example: Castle scheduled_delivery_timestamp: type: integer description: | The UNIX timestamp for when the message will be sent, in UTC seconds. example: 3165826990 read_by_sender: type: boolean description: | Whether the message should be initially marked read by its sender. If unspecified, the server uses a heuristic based on the client name and the recipient. **Changes**: New in Zulip 8.0 (feature level 236). example: true required: - type - to - content - scheduled_delivery_timestamp encoding: to: contentType: application/json scheduled_delivery_timestamp: contentType: application/json read_by_sender: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} scheduled_message_id: type: integer description: | The unique ID of the scheduled message. This is different from the unique ID that the message will have after it is sent. example: { "msg": "", "scheduled_message_id": 42, "result": "success", } "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/NonExistingChannelIdError" - description: | A typical failed JSON response for when a channel message is scheduled to be sent to a channel that does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid user ID 10", "result": "error", } description: | A typical failed JSON response for when a direct message is scheduled to be sent to a user that does not exist: /scheduled_messages/{scheduled_message_id}: patch: operationId: update-scheduled-message tags: ["scheduled_messages"] summary: Edit a scheduled message description: | Edit an existing [scheduled message](/help/schedule-a-message). **Changes**: New in Zulip 7.0 (feature level 184). parameters: - name: scheduled_message_id in: path schema: type: integer description: | The ID of the scheduled message to update. This is different from the unique ID that the message would have after being sent. required: true example: 2 requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: type: description: | The type of scheduled message to be sent. `"direct"` for a direct message and `"stream"` or `"channel"` for a channel message. When updating the type of the scheduled message, the `to` parameter is required. And, if updating the type of the scheduled message to `"stream"`/`"channel"`, then the `topic` parameter is also required. Note that, while `"private"` is supported for scheduling direct messages, clients are encouraged to use to the modern convention of `"direct"` to indicate this message type, because support for `"private"` may eventually be removed. **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as an additional value for this parameter to indicate the type of a channel message. type: string enum: - direct - channel - stream - private example: stream to: description: | The scheduled message's tentative target audience. For channel messages, the integer ID of the channel. For direct messages, a list containing integer user IDs. Required when updating the `type` of the scheduled message. oneOf: - type: integer - type: array items: type: integer minLength: 1 example: 11 content: description: | The updated content of the scheduled message. Clients should use the `max_message_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum message size. type: string example: Hello topic: description: | The updated topic of the scheduled message. Required when updating the `type` of the scheduled message to `"stream"` or `"channel"`. Ignored when the existing or updated `type` of the scheduled message is `"direct"` (or `"private"`). Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length. type: string example: Castle scheduled_delivery_timestamp: type: integer description: | The UNIX timestamp for when the message will be sent, in UTC seconds. Required when updating a scheduled message that the server has already tried and failed to send. This state is indicated with `"failed": true` in `scheduled_messages` objects; see response description at [`GET /scheduled_messages`](/api/get-scheduled-messages#response). example: 3165826990 encoding: to: contentType: application/json scheduled_delivery_timestamp: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} example: {"result": "success", "msg": ""} "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/NonExistingChannelIdError" - description: | A typical failed JSON response for when a channel message is scheduled to be sent to a channel that does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid user ID 10", "result": "error", } description: | A typical failed JSON response for when a direct message is scheduled to be sent to a user that does not exist: "404": description: Not Found. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when no scheduled message exists with the provided ID: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Scheduled message does not exist", } delete: operationId: delete-scheduled-message tags: ["scheduled_messages"] summary: Delete a scheduled message description: | Delete, and therefore cancel sending, a previously [scheduled message](/help/schedule-a-message). **Changes**: New in Zulip 7.0 (feature level 173). parameters: - name: scheduled_message_id in: path schema: type: integer description: | The ID of the scheduled message to delete. This is different from the unique ID that the message would have after being sent. required: true example: 1 responses: "200": $ref: "#/components/responses/SimpleSuccess" "404": description: Not Found. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when no scheduled message exists with the provided ID: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Scheduled message does not exist", } /default_streams: post: operationId: add-default-stream tags: ["channels"] summary: Add a default channel x-requires-administrator: true description: | Add a channel to the set of [default channels][default-channels] for new users joining the organization. [default-channels]: /help/set-default-channels-for-new-users requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the target channel. type: integer example: 10 required: - stream_id encoding: stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | A typical failed JSON response for when an invalid channel ID is passed: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Private channels cannot be made default.", "result": "error", } description: | A typical failed JSON response for when a user tries to add a private channel to the default channels set: delete: operationId: remove-default-stream summary: Remove a default channel tags: ["channels"] description: | Remove a channel from the set of [default channels][default-channels] for new users joining the organization. [default-channels]: /help/set-default-channels-for-new-users x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the target channel. type: integer example: 10 required: - stream_id encoding: stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | A typical failed JSON response for when an invalid channel ID is passed: /messages: get: operationId: get-messages summary: Get messages tags: ["messages"] description: | This endpoint is the primary way to fetch a messages. It is used by all official Zulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as many bots, API clients, backup scripts, etc. Most queries will specify a [narrow filter](/api/get-messages#parameter-narrow), to fetch the messages matching any supported [search query](/help/search-for-messages). If not specified, it will return messages corresponding to the user's [combined feed](/help/combined-feed). There are two ways to specify which messages matching the narrow filter to fetch: - A range of messages, described by an `anchor` message ID (or a string-format specification of how the server should computer an anchor to use) and a maximum number of messages in each direction from that anchor. - A rarely used variant (`message_ids`) where the client specifies the message IDs to fetch. The server returns the matching 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. Note that a user's message history does not contain messages sent to channels before they [subscribe](/api/subscribe), and newly created bot users are not usually subscribed to any channels. We recommend requesting at most 1000 messages in a batch, 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. **Changes**: The `message_ids` option is new in Zulip 10.0 (feature level 300). x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - client_gravatar - apply_markdown - use_first_unread_anchor - include_anchor - message_ids 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. Required if `message_ids` is not provided. schema: type: integer minimum: 0 example: 4 required: false - name: num_after in: query description: | The number of messages with IDs greater than the anchor to retrieve. Required if `message_ids` is not provided. schema: type: integer minimum: 0 example: 8 required: false - name: narrow in: query description: | The narrow where you want to fetch the messages from. See how to [construct a narrow](/api/construct-narrow). Note that many narrows, including all that lack a `channel`, `channels`, `stream`, or `streams` operator, search the user's personal message history. See [searching shared history](/help/search-for-messages#searching-shared-history) for details. For example, if you would like to fetch messages from all public channels instead of only the user's message history, then a specific narrow for messages sent to all public channels can be used: `{"operator": "channels", "operand": "public"}`. Newly created bot users are not usually subscribed to any channels, so bots using this API should either be subscribed to appropriate channels or use a shared history search narrow with this endpoint. **Changes**: See [changes section](/api/construct-narrow#changes) of search/narrow filter documentation. content: application/json: schema: type: array items: oneOf: - type: object required: - operator - operand additionalProperties: false properties: operator: type: string operand: oneOf: - type: string - type: integer - type: array items: type: integer negated: type: boolean - type: array items: type: string minItems: 2 maxItems: 2 default: [] example: [{"operand": "Denmark", "operator": "channel"}] - $ref: "#/components/parameters/ClientGravatar" - name: apply_markdown in: query description: | If `true`, message content is returned in the rendered HTML format. If `false`, message content is returned in the raw Markdown-format text that user entered. schema: type: boolean default: true example: false - name: use_first_unread_anchor in: query deprecated: true description: | Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older. Whether to use the (computed by the server) first unread message matching the narrow as the `anchor`. Mutually exclusive with `anchor`. **Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by `"anchor": "first_unread"`. schema: type: boolean default: false example: true - name: message_ids in: query description: | A list of message IDs to fetch. The server will return messages corresponding to the subset of the requested message IDs that exist and the current user has access to, potentially filtered by the narrow (if that parameter is provided). It is an error to pass this parameter as well as any of the parameters involved in specifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`, `num_before`, and `num_after`. **Changes**: New in Zulip 10.0 (feature level 300). Previously, there was no way to request a specific set of messages IDs. content: application/json: schema: type: array items: type: integer example: [1, 2, 3] responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false required: - result - msg - messages 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`). Only present if `message_ids` is not provided. found_newest: type: boolean description: | Whether the server promises that the `messages` list includes the very newest messages matching the narrow (used by clients that paginate their requests to decide whether there may be more messages to fetch). found_oldest: type: boolean description: | Whether the server promises that the `messages` list includes the very oldest messages matching the narrow (used by clients that paginate their requests to decide whether there may be more messages to fetch). found_anchor: type: boolean description: | Whether the anchor message is included in the response. If the message with the ID specified in the request does not exist, did not match the narrow, or was excluded via `"include_anchor": false`, this will be false. history_limited: type: boolean description: | Whether the message history was limited due to plan restrictions. This flag is set to `true` only when the oldest messages(`found_oldest`) matching the narrow is fetched. messages: type: array description: | An array of `message` objects. **Changes**: In Zulip 3.1 (feature level 26), the `sender_short_name` field was removed from message objects. items: allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: nullable: true client: {} content: {} content_type: {} display_recipient: {} edit_history: {} id: {} is_me_message: {} last_edit_timestamp: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} submessages: {} timestamp: {} topic_links: {} type: {} flags: type: array description: | The user's [message flags][message-flags] for the message. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level. [message-flags]: /api/update-message-flags#available-flags items: type: string match_content: type: string description: | Only present if keyword search was included among the narrow parameters. HTML content of a queried message that matches the narrow, with `` 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 `` 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": "Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.
", "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": "Wait, is this from the frontend js code or backend python code
", "flags": ["read"], "id": 21, "display_recipient": "Verona", "content_type": "text/html", "is_me_message": false, "timestamp": 1527939746, "sender_id": 4, "sender_full_name": "King Hamlet", "recipient_id": 20, "topic_links": [], "client": "populate_db", "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "submessages": [], "sender_email": "hamlet@zulip.com", "reactions": [], }, ], } post: operationId: send-message summary: Send a message tags: ["messages"] description: | Send a [channel message](/help/introduction-to-topics) or a [direct message](/help/direct-messages). requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: type: description: | The type of message to be sent. `"direct"` for a direct message and `"stream"` or `"channel"` for a channel message. **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as an additional value for this parameter to request a channel message. In Zulip 7.0 (feature level 174), `"direct"` was added as the preferred way to request a direct message, deprecating the original `"private"`. While `"private"` is still supported for requesting direct messages, clients are encouraged to use to the modern convention with servers that support it, because support for `"private"` will eventually be removed. type: string enum: - direct - channel - stream - private example: direct to: description: | For channel messages, either the name or integer ID of the channel. For direct messages, either a list containing integer user IDs or a list containing string Zulip API email addresses. **Changes**: Support for using user/channel IDs was added in Zulip 2.0.0. oneOf: - type: string - type: integer - type: array items: type: string - type: array items: type: integer minLength: 1 example: [9, 10] content: $ref: "#/components/schemas/RequiredContent" topic: description: | The topic of the message. Only required for channel messages (`"type": "stream"` or `"type": "channel"`), ignored otherwise. Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length. **Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded this as `subject`, which is currently a deprecated alias. type: string example: Castle queue_id: type: string description: | For clients supporting [local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo), the [event queue](/api/register-queue) ID for the client. If passed, `local_id` is required. If the message is successfully sent, the server will include `local_id` in the `message` event that the client with this `queue_id` will receive notifying it of the new message via [`GET /events`](/api/get-events). This lets the client know unambiguously that it should replace the locally echoed message, rather than adding this new message (which would be correct if the user had sent the new message from another device). example: "fb67bf8a-c031-47cc-84cf-ed80accacda8" local_id: type: string description: | For clients supporting local echo, a unique string-format identifier chosen freely by the client; the server will pass it back to the client without inspecting it, as described in the `queue_id` description. example: "100.01" read_by_sender: type: boolean description: | Whether the message should be initially marked read by its sender. If unspecified, the server uses a heuristic based on the client name. **Changes**: New in Zulip 8.0 (feature level 236). example: true required: - type - to - content encoding: to: contentType: application/json read_by_sender: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false required: - id properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: | The unique ID assigned to the sent message. automatic_new_visibility_policy: type: integer enum: - 2 - 3 description: | If the message's sender had configured their [visibility policy settings](/help/mute-a-topic) to potentially automatically follow or unmute topics when sending messages, and one of these policies did in fact change the user's visibility policy for the topic where this message was sent, the new value for that user's visibility policy for the recipient topic. Only present if the sender's visibility was in fact changed. The value can be either [unmuted or followed](/api/update-user-topic#parameter-visibility_policy). Clients will also be notified about the change in policy via a `user_topic` event as usual. This field is intended to be used by clients to explicitly inform the user when a topic's visibility policy was changed automatically due to sending a message. For example, the Zulip web application uses this field to decide whether to display a warning or notice suggesting to unmute the topic after sending a message to a muted channel. Such a notice would be confusing in the event that the act of sending the message had already resulted in the user automatically unmuting or following the topic in question. **Changes**: New in Zulip 8.0 (feature level 218). example: { "msg": "", "id": 42, "automatic_new_visibility_policy": 2, "result": "success", } "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/NonExistingChannelNameError" - description: | A typical failed JSON response for when a channel message is sent to a channel that does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid email 'eeshan@zulip.com'", "result": "error", } description: | A typical failed JSON response for when a direct message is sent to a user that does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "You do not have permission to use channel wildcard mentions in this channel.", "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED", } description: | An example JSON error response for when the message was rejected because of the organization's `wildcard_mention_policy` and large number of subscribers to the channel. **Changes**: New in Zulip 8.0 (feature level 229). Previously, this error returned the `"BAD_REQUEST"` code. - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "You do not have permission to use topic wildcard mentions in this topic.", "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED", } description: | An example JSON error response for when the message was rejected because the message contains a topic wildcard mention, but the user doesn't have permission to use such a mention in this topic due to the `wildcard_mention_policy` (and large number of participants in this specific topic). **Changes**: New in Zulip 8.0 (feature level 229). Previously, `wildcard_mention_policy` was not enforced for topic mentions. /messages/{message_id}/history: get: operationId: get-message-history summary: Get a message's edit history tags: ["messages"] description: | Fetch the message edit history of a previously edited message. Note that edit history may be disabled in some organizations; see the [Zulip Help Center documentation on editing messages][edit-settings]. [edit-settings]: /help/view-a-messages-edit-history parameters: - $ref: "#/components/parameters/MessageId" x-response-description: | Please note that the original message's snapshot only contains the fields `topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This snapshot will be the only one present if the message has never been edited. Also note that each snapshot object will only contain additional data for the modified fields for that particular edit (e.g. if only the topic or channel was edited, `prev_content`, `prev_rendered_content`, and `content_html_diff` will not appear). responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} message_history: type: array items: type: object additionalProperties: false properties: topic: type: string description: | The topic of the message immediately after this edit event. prev_topic: type: string description: | Only present if message's topic was edited. The topic of the message immediately prior to this edit event. stream: type: integer description: | Only present if message's channel was edited. The ID of the channel containing the message immediately after this edit event. **Changes**: New in Zulip 5.0 (feature level 118). prev_stream: type: integer description: | Only present if message's channel was edited. The ID of the channel containing the message immediately prior to this edit event. **Changes**: New in Zulip 3.0 (feature level 1). content: type: string description: | The raw Markdown content of the message immediately after this edit event. rendered_content: type: string description: | The rendered HTML representation of `content`. prev_content: type: string description: | Only present if message's content was edited. The raw Markdown content of the message immediately prior to this edit event. prev_rendered_content: type: string description: | Only present if message's content was edited. The rendered HTML representation of `prev_content`. user_id: type: integer nullable: true description: | The ID of the user that made the edit. Will be `null` only for edit history events predating March 2017. Clients can display edit history events where this is `null` as modified by either the sender (for content edits) or an unknown user (for topic edits). content_html_diff: type: string description: | Only present if message's content was edited. An HTML diff between this version of the message and the previous one. timestamp: type: integer description: | The UNIX timestamp for this edit. description: | A chronologically sorted, oldest to newest, array of `snapshot` objects, each one with the values of the message after the edit. example: { "message_history": [ { "content": "Hello!", "topic": "party at my houz", "rendered_content": "Hello!
", "timestamp": 1530129122, "user_id": 5, }, { "topic": "party at my house", "content": "Howdy!", "prev_content": "Hello!", "rendered_content": "Howdy!
", "user_id": 5, "prev_rendered_content": "Hello!
", "content_html_diff": 'Howdy!
Hello!
| Flag | Purpose |
|---|---|
read |
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. |
starred |
Whether the user has starred this message. |
collapsed |
Whether the user has collapsed this message. |
mentioned |
Whether the current user was mentioned 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. |
stream_wildcard_mentioned |
Whether this message contained a
channel wildcard mention
(like @**all**). Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a channel wildcard mention.
Changes: New in Zulip 8.0 (feature level 224). |
topic_wildcard_mentioned |
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). |
has_alert_word |
Whether the message contains any of the current user's configured alert words. 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. |
historical |
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 channel
before they subscribed to that channel). Cannot be
changed by the user directly.
|
wildcard_mentioned |
Whether this message contained either a
channel wildcard mention
(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 channel and/or topic wildcard
mention.
Changes: Deprecated in Zulip 8.0 (feature level 224), in favor of the stream_wildcard_mentioned and
topic_wildcard_mentioned flags. The
wildcard_mentioned flag exists for backwards compatibility
with older clients and equals
stream_wildcard_mentioned || topic_wildcard_mentioned.
Clients supporting older server versions should treat this field as a
previous name for the stream_wildcard_mentioned flag as
topic wildcard mentions were not available prior to this feature level.
|
foo
", "result": "success", } /messages/{message_id}/reactions: post: operationId: add-reaction summary: Add an emoji reaction tags: ["messages"] description: | Add an [emoji reaction](/help/emoji-reactions) to a message. x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - emoji_code - reaction_type parameters: - $ref: "#/components/parameters/MessageId" requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: emoji_name: description: | The target emoji's human-readable name. To find an emoji's name, hover over a message to reveal three icons on the right, then click the smiley face icon. Images of available reaction emojis appear. Hover over the emoji you want, and note that emoji's text name. type: string example: "octopus" emoji_code: $ref: "#/components/schemas/EmojiCode" reaction_type: $ref: "#/components/schemas/ReactionType" required: - emoji_name responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid emoji code", "code": "BAD_REQUEST", } description: | An example JSON error response for when the emoji code is invalid: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Reaction already exists.", "code": "REACTION_ALREADY_EXISTS", } description: | An example JSON error response for when the reaction already exists. **Changes**: New in Zulip 8.0 (feature level 193). Previously, this error returned the `"BAD_REQUEST"` code. delete: operationId: remove-reaction summary: Remove an emoji reaction tags: ["messages"] description: | Remove an [emoji reaction](/help/emoji-reactions) from a message. x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - emoji_code - reaction_type parameters: - $ref: "#/components/parameters/MessageId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: emoji_name: description: | The target emoji's human-readable name. To find an emoji's name, hover over a message to reveal three icons on the right, then click the smiley face icon. Images of available reaction emojis appear. Hover over the emoji you want, and note that emoji's text name. type: string example: "octopus" emoji_code: $ref: "#/components/schemas/EmojiCode" reaction_type: $ref: "#/components/schemas/ReactionType" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid emoji code", "code": "BAD_REQUEST", } description: | An example JSON error response for when the emoji code is invalid: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Reaction doesn't exist.", "code": "REACTION_DOES_NOT_EXIST", } description: | An example JSON error response for when the reaction does not exist. **Changes**: New in Zulip 8.0 (feature level 193). Previously, this error returned the `"BAD_REQUEST"` code. /messages/{message_id}/read_receipts: get: operationId: get-read-receipts summary: Get a message's read receipts tags: ["messages"] description: | Returns a list containing the IDs for all users who have marked the message as read (and whose privacy settings allow sharing that information). The list of users IDs will include any bots who have marked the message as read via the API (providing a way for bots to indicate whether they have processed a message successfully in a way that can be easily inspected in a Zulip client). Bots for which this behavior is not desired may disable the `send_read_receipts` setting via the API. It will never contain the message's sender. **Changes**: New in Zulip 6.0 (feature level 137). parameters: - $ref: "#/components/parameters/MessageId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user_ids: type: array description: | An array of IDs of users who have marked the target message as read and whose read status is available to the current user. The IDs of users who have disabled sending read receipts (`"send_read_receipts": false`) will never appear in the response, nor will the message's sender. Additionally, the IDs of any users who have been muted by the current user or who have muted the current user will not be included in the response. The current user's ID will appear if they have marked the target message as read. **Changes**: Prior to Zulip 6.0 (feature level 143), the IDs of users who have been muted by or have muted the current user were included in the response. items: type: integer example: {"msg": "", "result": "success", "user_ids": [3, 7, 9]} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidMessageError" - description: | A typical JSON response when attempting to access read receipts for a message ID that either does not exist or is not accessible to the current user: /messages/matches_narrow: get: operationId: check-messages-match-narrow summary: Check if messages match a narrow tags: ["messages"] description: | Check whether a set of messages match a [narrow](/api/construct-narrow). For many common narrows (e.g. a topic), clients can write an efficient client-side check to determine whether a newly arrived message belongs in the view. This endpoint is designed to allow clients to handle more complex narrows for which the client does not (or in the case of full-text search, cannot) implement this check. The format of the `match_subject` and `match_content` objects is designed to match those returned by the [`GET /messages`](/api/get-messages#response) endpoint, so that a client can splice these fields into a `message` object received from [`GET /events`](/api/get-events#message) and end up with an extended message object identical to how a [`GET /messages`](/api/get-messages) request for the current narrow would have returned the message. parameters: - name: msg_ids in: query description: List of IDs for the messages to check. content: application/json: schema: type: array items: type: integer example: [31, 32] required: true - name: narrow in: query description: | A structure defining the narrow to check against. See how to [construct a narrow](/api/construct-narrow). **Changes**: See [changes section](/api/construct-narrow#changes) of search/narrow filter documentation. content: application/json: schema: type: array items: type: object example: [{"operator": "has", "operand": "link"}] required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} messages: type: object description: | A dictionary with a key for each queried message that matches the narrow, with message IDs as keys and search rendering data as values. additionalProperties: type: object additionalProperties: false properties: match_content: type: string description: | HTML content of a queried message that matches the narrow. If the narrow is a search narrow, `` 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, `` 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": '', "match_subject": "test_topic", }, }, } /messages/{message_id}: get: operationId: get-message summary: Fetch a single message tags: ["messages"] description: | Given a message ID, return the message object. Additionally, a `raw_content` field is included. This field is useful for clients that primarily work with HTML-rendered messages but might need to occasionally fetch the message's raw Markdown (e.g. for [view source](/help/view-the-markdown-source-of-a-message) or prefilling a message edit textarea). **Changes**: Before Zulip 5.0 (feature level 120), this endpoint only returned the `raw_content` field. parameters: - $ref: "#/components/parameters/MessageId" - name: apply_markdown in: query description: | If `true`, message content is returned in the rendered HTML format. If `false`, message content is returned in the raw Markdown-format text that user entered. **Changes**: New in Zulip 5.0 (feature level 120). schema: type: boolean default: true example: false responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} raw_content: type: string deprecated: true description: | The raw Markdown content of the message. **Deprecated** and to be removed once no longer required for legacy clients. Modern clients should prefer passing `"apply_markdown": false` to request raw message content. message: description: | An object containing details of the message. **Changes**: New in Zulip 5.0 (feature level 120). allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: nullable: true client: {} content: {} content_type: {} display_recipient: {} edit_history: {} id: {} is_me_message: {} last_edit_timestamp: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} submessages: {} timestamp: {} topic_links: {} type: {} flags: type: array description: | The user's [message flags][message-flags] for the message. **Changes**: In Zulip 8.0 (feature level 224), the `wildcard_mentioned` flag was deprecated in favor of the `stream_wildcard_mentioned` and `topic_wildcard_mentioned` flags. The `wildcard_mentioned` flag exists for backwards compatibility with older clients and equals `stream_wildcard_mentioned || topic_wildcard_mentioned`. Clients supporting older server versions should treat this field as a previous name for the `stream_wildcard_mentioned` flag as topic wildcard mentions were not available prior to this feature level. [message-flags]: /api/update-message-flags#available-flags items: type: string example: { "raw_content": "**Don't** forget your towel!", "result": "success", "msg": "", "message": { "subject": "", "sender_realm_str": "zulip", "type": "private", "content": "Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.
", "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: | Update the content, topic, or channel of the message with the specified ID. You can [resolve topics](/help/resolve-a-topic) by editing the topic to `✔ {original_topic}` with the `propagate_mode` parameter set to `"change_all"`. See [configuring message editing][config-message-editing] for detailed documentation on when users are allowed to edit message content, and [restricting moving messages][restrict-move-messages] for detailed documentation on when users are allowed to change a message's topic and/or channel. The relevant realm settings in the API that are related to the above linked documentation on when users are allowed to update messages are: - `allow_message_editing` - `can_move_messages_between_channels_group` - `edit_topic_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**: In Zulip 10.0 (feature level 310), `move_messages_between_streams_policy` was removed and replaced by `can_move_messages_between_channels_group` realm setting. Prior to Zulip 7.0 (feature level 172), anyone could add a topic to channel messages without a topic, regardless of the organization's [topic editing permissions](/help/restrict-moving-messages). As of this feature level, messages without topics have the same restrictions for topic edits as messages with topics. Before Zulip 7.0 (feature level 172), by using the `change_all` value for the `propagate_mode` parameter, users could move messages after the organization's configured time limits for changing a message's topic or channel had passed. As of this feature level, the server will [return an error](/api/update-message#response) with `"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"` if users, other than organization administrators or moderators, try to move messages after these time limits have passed. Before Zulip 7.0 (feature level 162), users who were not administrators or moderators could only edit topics if the target message was sent within the last 3 days. As of this feature level, that time limit is now controlled by the realm setting `move_messages_within_stream_limit_seconds`. Also at this feature level, a similar time limit for moving messages between channels was added, controlled by the realm setting `move_messages_between_streams_limit_seconds`. Previously, all users who had permission to move messages between channels did not have any time limit restrictions when doing so. Before Zulip 7.0 (feature level 159), editing channels and topics of messages was forbidden if the realm setting for `allow_message_editing` was `false`, regardless of an organization's configuration for the realm settings `edit_topic_policy` or `move_messages_between_streams_policy`. Before Zulip 7.0 (feature level 159), message senders were allowed to edit the topic of their messages indefinitely. In Zulip 5.0 (feature level 75), the `edit_topic_policy` realm setting was added, replacing the `allow_community_topic_editing` boolean. In Zulip 4.0 (feature level 56), the `move_messages_between_streams_policy` realm setting was added. [config-message-editing]: /help/restrict-message-editing-and-deletion [restrict-move-messages]: /help/restrict-moving-messages x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - stream_id parameters: - $ref: "#/components/parameters/MessageId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: topic: description: | The topic to move the message(s) to, to request changing the topic. Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length Should only be sent when changing the topic, and will throw an error if the target message is not a channel message. **Changes**: New in Zulip 2.0.0. Previous Zulip releases encoded this as `subject`, which is currently a deprecated alias. type: string example: Castle propagate_mode: description: | Which message(s) should be edited: - `"change_later"`: The target message and all following messages. - `"change_one"`: Only the target message. - `"change_all"`: All messages in this topic. Only the default value of `"change_one"` is valid when editing only the content of a message. This parameter determines both which messages get moved and also whether clients that are currently narrowed to the topic containing the message should navigate or adjust their compose box recipient to point to the post-edit channel/topic. type: string enum: - change_one - change_later - change_all default: change_one example: change_all send_notification_to_old_thread: description: | Whether to send an automated message to the old topic to notify users where the messages were moved to. **Changes**: Before Zulip 6.0 (feature level 152), this parameter had a default of `true` and was ignored unless the channel was changed. New in Zulip 3.0 (feature level 9). type: boolean default: false example: true send_notification_to_new_thread: description: | Whether to send an automated message to the new topic to notify users where the messages came from. If the move is just [resolving/unresolving a topic](/help/resolve-a-topic), this parameter will not trigger an additional notification. **Changes**: Before Zulip 6.0 (feature level 152), this parameter was ignored unless the channel was changed. New in Zulip 3.0 (feature level 9). type: boolean default: true example: true content: $ref: "#/components/schemas/OptionalContent" stream_id: description: | The channel ID to move the message(s) to, to request moving messages to another channel. Should only be sent when changing the channel, and will throw an error if the target message is not a channel message. Note that a message's content and channel cannot be changed at the same time, so sending both `content` and `stream_id` parameters will throw an error. **Changes**: New in Zulip 3.0 (feature level 1). type: integer example: 43 encoding: send_notification_to_old_thread: contentType: application/json send_notification_to_new_thread: contentType: application/json stream_id: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} detached_uploads: type: array description: | Details on all files uploaded by the acting user whose only references were removed when editing this message. Clients should ask the acting user if they wish to delete the uploaded files returned in this response, which might otherwise remain visible only in message edit history. Note that [access to message edit history](/help/disable-message-edit-history) is configurable; this detail may be important in presenting the question clearly to users. New in Zulip 10.0 (feature level 285). items: $ref: "#/components/schemas/Attachments" example: { "result": "success", "msg": "", "detached_uploads": [ { "id": 3, "name": "1253601-1.jpg", "path_id": "2/5d/BD5NRptFxPDKY3RUKwhhup8r/1253601-1.jpg", "size": 1339060, "create_time": 1687984706000, "messages": [], }, ], } "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - properties: msg: enum: - Your organization has turned off message editing - You don't have permission to edit this message - The time limit for editing this message has past - Nothing to change - Topic can't be empty example: { "code": "BAD_REQUEST", "msg": "You don't have permission to edit this message", "result": "error", } description: | A typical JSON response for when one doesn't have the permission to edit a particular message: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED", "first_message_id_allowed_to_move": 123, "msg": "You only have permission to move the 2/5 most recent messages in this topic.", "result": "error", "total_messages_allowed_to_move": 2, "total_messages_in_topic": 5, } description: | A special failed JSON response (`"code": "MOVE_MESSAGES_TIME_LIMIT_EXCEEDED"`) for when the user has permission to move the target message, but asked to move all messages in a topic (`"propagate_mode": "change_all"`) and the user does not have permission to move the entire topic. This happens when the topic contains some messages that are older than an applicable time limit for the requested topic move (see `move_messages_within_stream_limit_seconds` and/or `move_messages_between_streams_limit_seconds` in the [`POST /register`](/api/register-queue) response). The error response contains data on which portion of this topic the user has permission to move. `first_message_id_allowed_to_move` is the oldest message ID in this topic that the user has permission to move. There are `total_messages_in_topic` in the topic, but the user only has permission to move the (most recent) `total_messages_allowed_to_move` messages. Clients should support this error code with `"first_message_id_allowed_to_move": null` for forward compatibility with future server versions that may use this error code with other propagation modes where the user does not have permission to move any messages, or where the server did not calculate the total message counts noted above. Clients can either only present the error to the user or, if `first_message_id_allowed_to_move` is not `null`, prompt the user to adjust their query with the above information. If clients choose to present a prompt for this error code, they should recommend the option of cancelling and (manually) asking a moderator to move the entire topic, since that's often a better experience than partially moving a topic. This API supports a client that wishes to allow the user to repeat the request with a `change_later` propagation mode and a target message ID of `first_message_id_allowed_to_move`, if the user desires to move only the portion of the topic that they can. Note that in a channel with [protected history](/help/channel-permissions), the Zulip security model requires that the above calculations only include messages the acting user has access to. So in the rare case of a user attempting to move a topic that started before the user joined a private channel with protected history, this API endpoint might move only the portion of a topic that they have access to, without this error or any confirmation dialog. **Changes**: New in Zulip 7.0 (feature level 172). - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "You do not have permission to use channel wildcard mentions in this channel.", "code": "STREAM_WILDCARD_MENTION_NOT_ALLOWED", } description: | An example JSON error response for when the message was rejected because of the organization's `wildcard_mention_policy` and large number of subscribers to the channel. **Changes**: New in Zulip 8.0 (feature level 229). Previously, this error returned the `"BAD_REQUEST"` code. - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "You do not have permission to use topic wildcard mentions in this topic.", "code": "TOPIC_WILDCARD_MENTION_NOT_ALLOWED", } description: | An example JSON error response for when the message was rejected because the message contains a topic wildcard mention, but the user doesn't have permission to use such a mention in this topic due to the `wildcard_mention_policy` (and large number of participants in this specific topic). **Changes**: New in Zulip 8.0 (feature level 229). Previously, `wildcard_mention_policy` was not enforced for topic mentions. delete: operationId: delete-message summary: Delete a message tags: ["messages"] description: | Permanently delete a message. This API corresponds to the [delete a message completely][delete-completely] feature documented in the Zulip Help Center. [delete-completely]: /help/delete-a-message#delete-a-message-completely x-requires-administrator: true parameters: - $ref: "#/components/parameters/MessageId" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/InvalidMessageError" - description: | An example JSON response for when the specified message does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - description: | An example JSON response for when the user making the query does not have permission to delete the message: example: { "code": "BAD_REQUEST", "msg": "You don't have permission to delete this message", "result": "error", } /user_uploads: post: operationId: upload-file summary: Upload a file tags: ["messages"] description: | Upload a single file and get the corresponding URL. Initially, only you will be able to access the link. To share the uploaded file, you'll need to [send a message][send-message] containing the resulting link. Users who can already access the link can reshare it with other users by sending additional Zulip messages containing the link. For uploading larger files, `/api/v1/tus` is an endpoint implementing the [`tus` protocol](https://tus.io/protocols/resumable-upload) for resumable uploads. Clients which send authenticated credentials (either via browser-based cookies, or API key via `Authorization` header) may use this endpoint to create uploads. [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 100MB. [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings requestBody: content: multipart/form-data: schema: type: object properties: filename: type: string format: binary example: /path/to/file responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} uri: type: string deprecated: true description: | The URL of the uploaded file. Alias of `url`. **Changes**: Deprecated in Zulip 9.0 (feature level 272). The term "URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals). url: type: string description: | The URL of the uploaded file. **Changes**: New in Zulip 9.0 (feature level 272). Previously, this property was only available under the legacy `uri` name. filename: type: string description: | The filename that Zulip stored the upload as. This usually differs from the basename of the URL when HTML escaping is required to generate a valid URL. Clients generating a Markdown link to a newly uploaded file should do so by combining the `url` and `filename` fields in the response as follows: `[{filename}]({url})`, with care taken to clean `filename` of `[` and `]` characters that might break Markdown rendering. **Changes**: New in Zulip 10.0 (feature level 285). example: { "msg": "", "result": "success", "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", "url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", "filename": "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": "I am:
\n+0-11-23-456-7890
", }, "8": {"value": "zulipbot"}, "3": { "rendered_value": "Dark chocolate
", "value": "Dark chocolate", }, }, "user_id": 10, "is_bot": false, "bot_type": null, "timezone": "", "is_admin": false, "is_owner": false, "is_billing_admin": false, "role": 400, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com", "delivery_email": null, }, { "bot_owner_id": 11, "is_guest": false, "date_joined": "2019-10-20T12:52:17.862053+00:00", "full_name": "Iago's Bot", "email": "iago-bot@zulipdev.com", "delivery_email": "iago-bot@zulipdev.com", "is_active": true, "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", "is_admin": false, "is_owner": false, "is_billing_admin": false, "role": 400, "user_id": 23, "bot_type": 1, "timezone": "", "is_bot": true, }, ], } post: operationId: create-user summary: Create a user tags: ["users"] description: | Create a new user account via the API. !!! warn "" **Note**: On Zulip Cloud, this feature is available only for organizations on a [Zulip Cloud Standard](https://zulip.com/plans/) or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators can request the required `can_create_users` permission for a bot or user by contacting [Zulip Cloud support][support] with an explanation for why it is needed. Self-hosted installations can toggle `can_create_users` on an account using the `manage.py change_user_role` [management command][management-commands]. **Changes**: Before Zulip 4.0 (feature level 36), this endpoint was available to all organization administrators. [support]: /help/contact-support [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: email: description: | The email address of the new user. type: string example: username@example.com password: description: | The password of the new user. type: string example: abcd1234 full_name: description: | The full name of the new user. type: string example: New User required: - email - password - full_name responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user_id: type: integer description: | The ID assigned to the newly created user. **Changes**: New in Zulip 4.0 (feature level 30). example: {"msg": "", "result": "success", "user_id": 25} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Email 'newbie@zulip.com' already in use", "result": "error", } description: | A typical JSON response for when another user with the same email address already exists in the realm: /users/{user_id}/reactivate: post: operationId: reactivate-user summary: Reactivate a user tags: ["users"] x-requires-administrator: true description: | [Reactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. parameters: - $ref: "#/components/parameters/UserId" responses: "200": $ref: "#/components/responses/SimpleSuccess" /users/{user_id}/status: get: operationId: get-user-status summary: Get a user's status tags: ["users"] description: | Get the [status](/help/status-and-availability) currently set by a user in the organization. **Changes**: New in Zulip 9.0 (feature level 262). Previously, user statuses could only be fetched via the [`POST /register`](/api/register-queue) endpoint. parameters: - $ref: "#/components/parameters/UserId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} status: allOf: - description: | The status set by the user. Note that, if the user doesn't have a status currently set, then the returned dictionary will be empty as none of the keys listed below will be present. - $ref: "#/components/schemas/UserStatus" example: { "result": "success", "msg": "", "status": { "status_text": "on vacation", "emoji_name": "car", "emoji_code": "1f697", "reaction_type": "unicode_emoji", }, } "400": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "No such user", "code": "BAD_REQUEST", } description: | An example JSON error response when the user does not exist: /users/{user_id_or_email}/presence: get: operationId: get-user-presence summary: Get a user's presence tags: ["users"] description: | Get the presence status for a specific user. This endpoint is most useful for embedding data about a user's presence status in other sites (e.g. an employee directory). Full Zulip clients like mobile/desktop apps will want to use the [main presence endpoint](/api/get-presence), which returns data for all active users in the organization, instead. See [Zulip's developer documentation][subsystems-presence] for details on the data model for presence in Zulip. [subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html parameters: - name: user_id_or_email in: path description: | The ID or Zulip API email address of the user whose presence you want to fetch. **Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported identifying the user by Zulip API email. schema: type: string example: iago@zulip.com required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} presence: type: object description: | An object containing the presence details for the user. additionalProperties: type: object additionalProperties: false properties: timestamp: type: integer description: | When this update was received. If the timestamp is more than a few minutes in the past, the user is offline. status: type: string description: | Whether the user had recently interacted with Zulip at the time of the timestamp. Will be either `"active"` or `"idle"` description: | `{client_name}` or `"aggregated"`: Object containing the details of the user's presence. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always contain two keys, `"website"` and `"aggregated"`, with identical data. The server no longer stores which client submitted presence updates. Previously, the `{client_name}` keys for these objects were the names of the different clients where the user was logged in, for example `website` or `ZulipDesktop`. example: { "presence": { "website": {"timestamp": 1532697622, "status": "active"}, "aggregated": {"timestamp": 1532697622, "status": "active"}, }, "result": "success", "msg": "", } /users/me: get: operationId: get-own-user summary: Get own user tags: ["users"] description: | Get basic data about the user/bot that requests this endpoint. responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} avatar_url: type: string description: | URL for the requesting user's avatar. **Changes**: New in Zulip 2.1.0. example: "x" avatar_version: type: integer description: | Version for the requesting user's avatar. Used for cache-busting requests for the user's avatar. Clients generally shouldn't need to use this; most avatar URLs sent by Zulip will already end with `?v={avatar_version}`. **Changes**: New in Zulip 3.0 (feature level 10). example: 1 email: type: string description: | Zulip API email of the requesting user. example: "iago@zulip.com" full_name: type: string description: | Full name of the requesting user. example: "Iago" is_admin: type: boolean description: | A boolean indicating if the requesting user is an admin. example: true is_owner: type: boolean description: | A boolean indicating if the requesting user is an organization owner. **Changes**: New in Zulip 3.0 (feature level 8). example: false is_billing_admin: type: boolean description: | A boolean indicating if the requesting user is a billing administrator. **Changes**: New in Zulip 5.0 (feature level 73). example: false role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: | [Organization-level role](/api/roles-and-permissions) of the requesting user. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest **Changes**: New in Zulip 4.0 (feature level 59). is_guest: type: boolean description: | A boolean indicating if the requesting user is a guest. **Changes**: New in Zulip 3.0 (feature level 10). example: false is_bot: type: boolean description: | A boolean indicating if the requesting user is a bot. example: false is_active: type: boolean description: | A boolean specifying whether the requesting user account has been deactivated. **Changes**: New in Zulip 3.0 (feature level 10). example: true timezone: type: string description: | The time zone of the requesting user. **Changes**: New in Zulip 3.0 (feature level 10). example: "" date_joined: type: string description: | The time the requesting user's account was created. **Changes**: New in Zulip 3.0 (feature level 10). example: "2019-10-20T07:50:53.728864+00:00" max_message_id: type: integer deprecated: true description: | The integer ID of the last message received by the requesting user's account. **Deprecated**. We plan to remove this in favor of recommending using `GET /messages` with `"anchor": "newest"`. example: 30 user_id: type: integer description: | The user's ID. example: 1 delivery_email: type: string description: | The requesting user's real email address. **Changes**: Prior to Zulip 7.0 (feature level 163), this field was present only when `email_address_visibility` was restricted and the requesting user had permission to access realm users' emails. As of this feature level, this field is always present. profile_data: $ref: "#/components/schemas/profile_data" example: { "avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1", "avatar_version": 1, "email": "iago@zulip.com", "delivery_email": iago@zulip.com, "full_name": "Iago", "is_admin": true, "is_owner": false, "role": 200, "is_guest": false, "is_billing_admin": false, "is_bot": false, "is_active": true, "timezone": "", "date_joined": "2019-10-20T07:50:53.728864+00:00", "max_message_id": 30, "msg": "", "result": "success", "user_id": 5, "profile_data": { "5": {"value": "2000-01-01"}, "4": {"value": "emacs"}, "7": {"value": "[10]"}, "1": { "value": "+1-234-567-8901", "rendered_value": "+1-234-567-8901
", }, "2": { "rendered_value": "Betrayer of Othello.
", "value": "Betrayer of Othello.", }, "8": {"value": "zulip"}, "3": { "value": "Apples", "rendered_value": "Apples
", }, "6": { "value": "https://zulip.readthedocs.io/en/latest/", }, }, } delete: operationId: deactivate-own-user summary: Deactivate own user tags: ["users"] description: | Deactivates the current user's account. See also the administrative endpoint for [deactivating another user](/api/deactivate-user). This endpoint is primarily useful to Zulip clients providing a user settings UI. responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} entity: type: string description: | An internationalized string that notes if the current user is the only organization owner or the only user in the organization. is_last_owner: type: boolean description: | Whether the current user is the only organization owner (meaning there are other active users in the organization) or the only active user in the organization. required: - entity - is_last_owner example: { "code": "CANNOT_DEACTIVATE_LAST_USER", "msg": "Cannot deactivate the only organization owner", "result": "error", "entity": "organization owner", "is_last_owner": true, } description: | If the current user is the only organization owner or only user in the organization, their account cannot be deactivated and an error response will be returned. The `is_last_owner` field in the error response indicates whether the user is the only owner (`true`) or the only user (`false`). The `entity` field in the error response is a internationalized string that notes if the current user is the only organization owner or the only user. An example JSON error response when the current user is the only organization owner in the organization: /users/me/alert_words: get: operationId: get-alert-words summary: Get all alert words tags: ["users"] description: | Get all of the user's configured [alert words][alert-words]. [alert-words]: /help/dm-mention-alert-notifications#alert-words responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: | An array of strings, where each string is an alert word (or phrase) configured by the user. items: type: string example: { "result": "success", "msg": "", "alert_words": ["natural", "illustrious"], } post: operationId: add-alert-words summary: Add alert words tags: ["users"] description: | Add words (or phrases) to the user's set of configured [alert words][alert-words]. [alert-words]: /help/dm-mention-alert-notifications#alert-words requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: alert_words: description: | An array of strings to be added to the user's set of configured alert words. Strings already present in the user's set of alert words already are ignored. Alert words are case insensitive. type: array items: type: string example: ["foo", "bar"] required: - alert_words encoding: alert_words: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: | An array of strings, where each string is an alert word (or phrase) configured by the user. items: type: string example: { "result": "success", "msg": "", "alert_words": ["foo", "bar", "natural", "illustrious"], } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "alert_words[0] is too long (limit: 100 characters)", "result": "error", } description: | An example JSON response for when a supplied alert word (or phrase) exceeds the character limit: delete: operationId: remove-alert-words summary: Remove alert words tags: ["users"] description: | Remove words (or phrases) from the user's set of configured [alert words][alert-words]. Alert words are case insensitive. [alert-words]: /help/dm-mention-alert-notifications#alert-words requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: alert_words: description: | An array of strings to be removed from the user's set of configured alert words. Strings that are not in the user's set of alert words are ignored. type: array items: type: string example: ["foo"] required: - alert_words encoding: alert_words: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: | An array of strings, where each string is an alert word (or phrase) configured by the user. items: type: string example: { "result": "success", "msg": "", "alert_words": ["bar", "natural", "illustrious"], } /users/me/presence: post: operationId: update-presence summary: Update your presence tags: ["users"] description: | Update the current user's [presence][availability] and fetch presence data of other users in the organization. This endpoint is meant to be used by clients for both: - Reporting the current user's presence status (`"active"` or `"idle"`) to the server. - Obtaining the presence data of all other users in the organization via regular polling (in parallel with receiving [`presence` events](/api/get-events#presence)). Accurate user presence is one of the most expensive parts of any chat application (in terms of bandwidth and other resources). Therefore, it is important that clients implementing Zulip's user presence system use the modern [`last_update_id`](#parameter-last_update_id) protocol to minimize fetching duplicate user presence data. See [Zulip's developer documentation][subsystems-presence] for details on the data model for user presence in Zulip. The Zulip server is responsible for implementing [invisible mode][invisible], which disables sharing a user's presence data. Nonetheless, clients should check the `presence_enabled` field in user objects in order to display the current user as online or offline based on whether they are sharing their presence information. **Changes**: As of Zulip 8.0 (feature level 228), if the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is `true`, then user presence data in the response is [limited to users the current user can see/access][limit-visibility]. [subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html [limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users [invisible]: /help/status-and-availability#invisible-mode [availability]: /help/status-and-availability#availability requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: last_update_id: type: integer description: | The identifier that specifies what presence data the client already has received, which allows the server to only return more recent user presence data. This should be set to `-1` during initialization of the client in order to fetch all user presence data, unless the client is obtaining initial user presence metadata from the [`POST /register`](/api/register-queue) endpoint. In subsequent queries to this endpoint, this value should be set to the most recent value of `presence_last_update_id` returned by the server in this endpoint's response, which implements incremental fetching of user presence data. When this parameter is passed, the user presence data in the response will always be in the modern format. **Changes**: New in Zulip 9.0 (feature level 263). Previously, the server sent user presence data for all users who had been active in the last two weeks unconditionally. example: 5 history_limit_days: type: integer description: | Limits how far back in time to fetch user presence data. If not specified, defaults to 14 days. A value of N means that the oldest presence data fetched will be from at most N days ago. Note that this is only useful during the initial user presence data fetch, as subsequent fetches should use the `last_update_id` parameter, which will act as the limit on how much presence data is returned. `history_limit_days` is ignored if `last_update_id` is passed with a value greater than `0`, indicating that the client already has some presence data. **Changes**: New in Zulip 10.0 (feature level 288). example: 365 new_user_input: type: boolean description: | Whether the user has interacted with the client (e.g. moved the mouse, used the keyboard, etc.) since the previous presence request from this client. The server uses data from this parameter to implement certain [usage statistics](/help/analytics). User interface clients that might run in the background, without the user ever interacting with them, should be careful to only pass `true` if the user has actually interacted with the client in order to avoid corrupting usage statistics graphs. example: false default: false ping_only: type: boolean description: | Whether the client is sending a ping-only request, meaning it only wants to update the user's presence `status` on the server. Otherwise, also requests the server return user presence data for all users in the organization, which is further specified by the [`last_update_id`](#parameter-last_update_id) parameter. example: false default: false slim_presence: type: boolean description: | Legacy parameter for configuring the format (modern or legacy) in which the server will return user presence data for the organization. Modern clients should use [`last_update_id`](#parameter-last_update_id), which guarantees that user presence data will be returned in the modern format, and should not pass this parameter as `true` unless interacting with an older server. Legacy clients that do not yet support `last_update_id` may use the value of `true` to request the modern format for user presence data. **Note**: The legacy format for user presence data will be removed entirely in a future release. **Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using the modern `last_update_id` parameter is the recommended way to request the modern format for user presence data. New in Zulip 3.0 (no feature level as it was an unstable API at that point). example: false default: false deprecated: true status: type: string enum: - idle - active description: | The status of the user on this client. Clients should report the user as `"active"` on this device if the client knows that the user is presently using the device (and thus would potentially see a notification immediately), even if the user has not directly interacted with the Zulip client. Otherwise, it should report the user as `"idle"`. See the related [`new_user_input`](#parameter-new_user_input) parameter for how a client should report whether the user is actively using the Zulip client. example: active required: - status responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false required: - result - msg properties: result: {} msg: {} ignored_parameters_unsupported: {} presence_last_update_id: type: integer description: | The identifier for the latest user presence data returned in the `presences` data of the response. If a value was passed for `last_update_id`, then this is guaranteed to be equal to or greater than that value. If it is the same value, then that indicates to the client that there were no updates to previously received user presence data. The client should then pass this value as the `last_update_id` parameter when it next queries this endpoint, in order to only receive new user presence data and avoid redundantly fetching already known information. This will be `-1` if no value was passed for [`last_update_id`](#parameter-last_update_id) and no user presence data was returned by the server. This can happen, for example, if an organization has disabled presence. **Changes**: New in Zulip 9.0 (feature level 263). server_timestamp: type: number description: | Only present if `ping_only` is `false`. The time when the server fetched the `presences` data included in the response. presences: type: object description: | Only present if `ping_only` is `false`. A dictionary where each entry describes the presence details of a user in the Zulip organization. Entries can be in either the modern presence format or the legacy presence format. These entries will be the modern presence format when the `last_updated_id` parameter is passed, or when the deprecated `slim_presence` parameter is `true`. If the deprecated `slim_presence` parameter is `false` and the `last_updated_id` parameter is omitted, the entries will be in the legacy presence API format. **Note**: The legacy presence format should only be used when interacting with old servers. It will be removed as soon as doing so is practical. additionalProperties: description: | Will be one of these two formats (modern or legacy) for user presence data: oneOf: - $ref: "#/components/schemas/ModernPresenceFormat" - type: object description: | `{user_email}`: Presence data (legacy format) for the user with the specified Zulip API email. additionalProperties: $ref: "#/components/schemas/LegacyPresenceFormat" zephyr_mirror_active: type: boolean deprecated: true description: | Legacy property for a part of the Zephyr mirroring system. **Deprecated**. Clients should ignore this field. examples: modern-presence-format-example: description: | Modern presence format: value: { "msg": "", "presences": { "10": { "idle_timestamp": 1656958530, "active_timestamp": 1656958520, }, }, "result": "success", "server_timestamp": 1656958539.6287155, "presence_last_update_id": 1000, } legacy-presence-format-example: description: | Legacy presence format: value: { "msg": "", "presences": { "user@example.com": { "aggregated": { "client": "website", "status": "idle", "timestamp": 1594825445, }, "website": { "client": "website", "status": "idle", "timestamp": 1594825445, "pushable": false, }, }, }, "result": "success", "server_timestamp": 1656958539.6287155, "presence_last_update_id": 1000, } /users/me/status: post: operationId: update-status summary: Update your status tags: ["users"] description: | Change your [status](/help/status-and-availability). A request to this endpoint will only change the parameters passed. For example, passing just `status_text` requests a change in the status text, but will leave the status emoji unchanged. Clients that wish to set the user's status to a specific value should pass all supported parameters. **Changes**: In Zulip 5.0 (feature level 86), added support for `emoji_name`, `emoji_code`, and `reaction_type` parameters. requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: status_text: type: string description: | The text content of the status message. Sending the empty string will clear the user's status. **Note**: The limit on the size of the message is 60 characters. example: on vacation away: deprecated: true type: boolean description: | Whether the user should be marked as "away". **Changes**: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, `away` is a legacy way to access the user's `presence_enabled` setting, with `away = !presence_enabled`. To be removed in a future release. example: true emoji_name: type: string description: | The name for the emoji to associate with this status. **Changes**: New in Zulip 5.0 (feature level 86). example: car emoji_code: type: string description: | A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. **Changes**: New in Zulip 5.0 (feature level 86). example: 1f697 reaction_type: type: string description: | A string indicating the type of emoji. Each emoji `reaction_type` has an independent namespace for values of `emoji_code`. Must be one of the following values: - `unicode_emoji` : In this namespace, `emoji_code` will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification. - `realm_emoji` : In this namespace, `emoji_code` will be the ID of the uploaded [custom emoji](/help/custom-emoji). - `zulip_extra_emoji` : These are special emoji included with Zulip. In this namespace, `emoji_code` will be the name of the emoji (e.g. "zulip"). **Changes**: New in Zulip 5.0 (feature level 86). example: unicode_emoji encoding: away: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Client did not pass any new values.", "code": "BAD_REQUEST", } description: | An example JSON error response when no changes were requested: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "status_text is too long (limit: 60 characters)", "code": "BAD_REQUEST", } description: | An example JSON error response when the `status_text` message exceeds the limit of 60 characters: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.", "code": "BAD_REQUEST", } description: | An example JSON error response when `emoji_name` is not specified but `emoji_code` or `reaction_type` is specified: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Emoji 'invalid' does not exist", "code": "BAD_REQUEST", } description: | An example JSON error response when the emoji name does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid emoji name.", "code": "BAD_REQUEST", } description: | An example JSON error response when the emoji name is invalid: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid custom emoji.", "code": "BAD_REQUEST", } description: | An example JSON error response when the custom emoji is invalid: /users/me/{stream_id}/topics: get: operationId: get-stream-topics summary: Get topics in a channel tags: ["channels"] description: | Get all topics the user has access to in a specific channel. Note that for private channels with [protected history](/help/channel-permissions), the user will only have access to topics of messages sent after they [subscribed to](/api/subscribe) the channel. Similarly, a user's [bot](/help/bots-overview#bot-type) will only have access to messages sent after the bot was subscribed to the channel, instead of when the user subscribed. parameters: - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} topics: type: array description: | An array of objects with information about user-accessible topics in the specified channel, sorted by recency (i.e., the topic with the most recent message is ordered first). items: type: object additionalProperties: false properties: max_id: description: | The message ID of the last message sent to this topic. type: integer name: description: | The name of the topic. type: string example: { "msg": "", "result": "success", "topics": [ {"max_id": 26, "name": "Denmark3"}, {"max_id": 23, "name": "Denmark1"}, {"max_id": 6, "name": "Denmark2"}, ], } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the user is attempting to fetch the topics of a non-existing channel (or also a private channel they don't have access to): /users/me/subscriptions: get: operationId: get-subscriptions summary: Get subscribed channels tags: ["channels"] description: | Get all channels that the user is subscribed to. # operationId can be used to record which view function # corresponds to an endpoint. TODO: Add these for more # endpoints, and perhaps use this to provide links to implementations. x-curl-examples-parameters: oneOf: - type: include parameters: enum: - "" - type: exclude description: | You may pass the `include_subscribers` query parameter as follows: parameters: enum: - "" parameters: - $ref: "#/components/parameters/IncludeSubscribers" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" # TODO: Is this the best way to declare required elements in 200 responses? - required: - subscriptions additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subscriptions: type: array description: | A list of dictionaries where each dictionary contains information about one of the subscribed channels. **Changes**: Removed `email_address` field from the dictionary in Zulip 8.0 (feature level 226). Removed `role` field from the dictionary in Zulip 6.0 (feature level 133). items: $ref: "#/components/schemas/Subscriptions" example: { "msg": "", "result": "success", "subscriptions": [ { "audible_notifications": true, "color": "#e79ab5", "creator_id": null, "description": "A Scandinavian country", "desktop_notifications": true, "is_muted": false, "invite_only": false, "name": "Denmark", "pin_to_top": false, "push_notifications": false, "stream_id": 1, "subscribers": [7, 10, 11, 12, 14], }, { "audible_notifications": true, "color": "#e79ab5", "creator_id": 8, "description": "Located in the United Kingdom", "desktop_notifications": true, "is_muted": false, "invite_only": false, "name": "Scotland", "pin_to_top": false, "push_notifications": false, "stream_id": 3, "subscribers": [7, 11, 12, 14], }, ], } post: operationId: subscribe summary: Subscribe to a channel tags: ["channels"] description: | Subscribe one or more users to one or more channels. If any of the specified channels do not exist, they are automatically created. The initial [channel settings](/api/update-stream) will be determined by the optional parameters, like `invite_only`, detailed below. Note that the ability to subscribe oneself and/or other users to a specified channel depends on the [channel's privacy settings](/help/channel-permissions). **Changes**: Before Zulip 8.0 (feature level 208), if a user specified by the [`principals`][principals-param] parameter was a deactivated user, or did not exist, then an HTTP status code of 403 was returned with `code: "UNAUTHORIZED_PRINCIPAL"` in the error response. As of this feature level, an HTTP status code of 400 is returned with `code: "BAD_REQUEST"` in the error response for these cases. [principals-param]: /api/subscribe#parameter-principals x-curl-examples-parameters: oneOf: - type: include parameters: enum: - subscriptions - type: include description: | To subscribe another user to a channel, you may pass in the `principals` parameter, like so: parameters: enum: - subscriptions - principals requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: subscriptions: description: | A list of dictionaries containing the key `name` and value specifying the name of the channel to subscribe. If the channel does not exist a new channel is created. The description of the channel created can be specified by setting the dictionary key `description` with an appropriate value. type: array items: type: object additionalProperties: false properties: name: type: string description: | The name of the channel. Clients should use the `max_stream_name_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum channel name length. description: type: string description: | The [description](/help/change-the-channel-description) to use for a new channel being created, in text/markdown format. Clients should use the `max_stream_description_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum channel description length. required: - name example: no-description: value: {"name": "Verona"} with-description: value: {"name": "Verona", "description": "Italian city"} example: [{"name": "Verona", "description": "Italian city"}] principals: $ref: "#/components/schemas/Principals" authorization_errors_fatal: description: | A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private channel) should be considered fatal or not. When `true`, an authorization error is reported as such. When set to `false`, the response will be a 200 and any channels where the request encountered an authorization error will be listed in the `unauthorized` key. type: boolean default: true example: false announce: description: | If one of the channels specified did not exist previously and is thus created by this call, this determines whether [notification bot](/help/configure-automated-notices) will send an announcement about the new channel's creation. type: boolean default: false example: true invite_only: description: | As described above, this endpoint will create a new channel if passed a channel name that doesn't already exist. This parameters and the ones that follow are used to request an initial configuration of a created channel; they are ignored for channels that already exist. This parameter determines whether any newly created channels will be private channels. type: boolean default: false example: true is_web_public: description: | This parameter determines whether any newly created channels will be web-public channels. Note that creating web-public channels requires the `WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings] to be enabled on the Zulip server in question, the organization to have enabled the `enable_spectator_access` realm setting, and the current use to have permission under the organization's `can_create_web_public_channel_group` realm setting. [server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html **Changes**: New in Zulip 5.0 (feature level 98). type: boolean default: false example: true is_default_stream: description: | This parameter determines whether any newly created channels will be added as [default channels][default-channels] for new users joining the organization. [default-channels]: /help/set-default-channels-for-new-users **Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status could only be changed using the [dedicated API endpoint](/api/add-default-stream). type: boolean default: false example: true history_public_to_subscribers: $ref: "#/components/schemas/HistoryPublicToSubscribers" stream_post_policy: $ref: "#/components/schemas/ChannelPostPolicy" message_retention_days: $ref: "#/components/schemas/MessageRetentionDays" can_remove_subscribers_group: $ref: "#/components/schemas/CanRemoveSubscribersGroupId" required: - subscriptions encoding: subscriptions: contentType: application/json principals: contentType: application/json authorization_errors_fatal: contentType: application/json announce: contentType: application/json invite_only: contentType: application/json is_web_public: contentType: application/json is_default_stream: contentType: application/json history_public_to_subscribers: contentType: application/json stream_post_policy: contentType: application/json can_remove_subscribers_group: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subscribed: type: object description: | A dictionary where the key is the ID of the user and the value is a list of the names of the channels that user was subscribed to as a result of the request. **Changes**: Before Zulip 10.0 (feature level 289), the user keys were Zulip API email addresses, not user ID. additionalProperties: description: | `{id}`: List of the names of the channels that were subscribed to as a result of the query. type: array items: type: string already_subscribed: type: object description: | A dictionary where the key is the ID of the user and the value is a list of the names of the channels that where the user was not added as a subscriber in this request, because they were already a subscriber. **Changes**: Before Zulip 10.0 (feature level 289), the user keys were Zulip API email addresses, not user IDs. additionalProperties: description: | `{id}`: List of the names of the channels that the user is already subscribed to. type: array items: type: string unauthorized: type: array items: type: string description: | A list of names of channels that the requesting user/bot was not authorized to subscribe to. Only present if `"authorization_errors_fatal": false`. example: { "already_subscribed": {"1": ["testing-help"]}, "msg": "", "result": "success", "subscribed": {"2": ["testing-help"]}, } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "msg": "Unable to access channel (private).", "result": "error", "code": "BAD_REQUEST", } description: | An example JSON response for when the requesting user does not have access to a private channel and `"authorization_errors_fatal": true`: patch: operationId: update-subscriptions summary: Update subscriptions tags: ["channels"] description: | Update which channels you are subscribed to. requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: delete: description: | A list of channel names to unsubscribe from. type: array items: type: string example: ["Verona", "Denmark"] add: description: | A list of objects describing which channels to subscribe to, optionally including per-user subscription parameters (e.g. color) and if the channel is to be created, its description. type: array items: type: object additionalProperties: false properties: name: type: string color: type: string description: type: string example: [ {"name": "Verona"}, { "name": "Denmark", "color": "#e79ab5", "description": "A Scandinavian country", }, ] encoding: delete: contentType: application/json add: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - required: - subscribed - already_subscribed - removed additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subscribed: type: object description: | A dictionary where the key is the Zulip API email address of the user/bot and the value is a list of the names of the channels that were subscribed to as a result of the query. additionalProperties: description: | `{email_id}`: A list of the names of channels that the user was subscribed to as a result of the query. type: array items: type: string already_subscribed: type: object description: | A dictionary where the key is the Zulip API email address of the user/bot and the value is a list of the names of the channels that the user/bot is already subscribed to. additionalProperties: description: | `{email_id}`: A list of the names of channels that the user was already subscribed to. type: array items: type: string not_removed: type: array items: type: string description: | A list of the names of channels that the user is already unsubscribed from, and hence doesn't need to be unsubscribed. removed: type: array items: type: string description: | A list of the names of channels which were unsubscribed from as a result of the query. example: { "msg": "", "subscribed": {}, "already_subscribed": {"iago@zulip.com": ["Verona"]}, "not_removed": [], "removed": ["testing-help"], "result": "success", } delete: operationId: unsubscribe summary: Unsubscribe from a channel tags: ["channels"] description: | Unsubscribe yourself or other users from one or more channels. In addition to managing the current user's subscriptions, this endpoint can be used to remove other users from channels. This is possible in 3 situations: - Organization administrators can remove any user from any channel. - Users can remove a bot that they own from any channel that the user [can access](/help/channel-permissions). - Users can unsubscribe any user from a channel if they [have access](/help/channel-permissions) to the channel and are a member of the [user group](/api/get-user-groups) specified by the [`can_remove_subscribers_group`][can-remove-parameter] for the channel. **Changes**: Before Zulip 8.0 (feature level 208), if a user specified by the [`principals`][principals-param] parameter was a deactivated user, or did not exist, then an HTTP status code of 403 was returned with `code: "UNAUTHORIZED_PRINCIPAL"` in the error response. As of this feature level, an HTTP status code of 400 is returned with `code: "BAD_REQUEST"` in the error response for these cases. Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group` setting was named `can_remove_subscribers_group_id`. Before Zulip 7.0 (feature level 161), the `can_remove_subscribers_group_id` for all channels was always the system group for organization administrators. Before Zulip 6.0 (feature level 145), users had no special privileges for managing bots that they own. [principals-param]: /api/unsubscribe#parameter-principals [can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group x-curl-examples-parameters: oneOf: - type: include description: | **Note**: Unsubscribing another user from a channel requires administrative privileges. parameters: enum: - subscriptions - type: exclude parameters: enum: - "" description: | You may specify the `principals` parameter like so: requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: subscriptions: description: | A list of channel names to unsubscribe from. This parameter is called `streams` in our Python API. type: array items: type: string example: ["Verona", "Denmark"] principals: $ref: "#/components/schemas/Principals" required: - subscriptions encoding: subscriptions: contentType: application/json principals: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} not_removed: type: array items: type: string description: | A list of the names of channels that the user is already unsubscribed from, and hence doesn't need to be unsubscribed. removed: type: array items: type: string description: | A list of the names of channels which were unsubscribed from as a result of the query. example: { "msg": "", "not_removed": [], "removed": ["testing-help"], "result": "success", } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/NonExistingChannelNameError" - description: | A typical failed JSON response for when the target channel does not exist: /users/me/subscriptions/muted_topics: patch: deprecated: true operationId: mute-topic summary: Topic muting tags: ["channels"] description: | [Mute or unmute a topic](/help/mute-a-topic) within a channel that the current user is subscribed to. **Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting to newer servers should use the [POST /user_topics](/api/update-user-topic) endpoint, as this endpoint may be removed in a future release. Before Zulip 7.0 (feature level 169), this endpoint returned an error if asked to mute a topic that was already muted or asked to unmute a topic that had not previously been muted. x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - stream_id requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the channel to access. Clients must provide either `stream` or `stream_id` as a parameter to this endpoint, but not both. **Changes**: New in Zulip 2.0.0. type: integer example: 43 stream: description: | The name of the channel to access. Clients must provide either `stream` or `stream_id` as a parameter to this endpoint, but not both. Clients should use `stream_id` instead of the `stream` parameter when possible. type: string example: Denmark topic: description: | The topic to (un)mute. Note that the request will succeed regardless of whether any messages have been sent to the specified topic. Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length. type: string example: dinner op: description: | Whether to mute (`add`) or unmute (`remove`) the provided topic. type: string enum: - add - remove example: add required: - topic - op encoding: stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" /mobile_push/test_notification: post: operationId: test-notify summary: Send a test notification to mobile device(s) tags: ["mobile"] description: | Trigger sending a test push notification to the user's selected mobile device or all of their mobile devices. **Changes**: Starting with Zulip 8.0 (feature level 234), test notifications sent via this endpoint use `test` rather than `test-by-device-token` in the `event` field. Also, as of this feature level, all mobile push notifications now include a `realm_name` field. New in Zulip 8.0 (feature level 217). requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: token: description: | The push token for the device to which to send the test notification. If this parameter is not submitted, the test notification will be sent to all of the user's devices registered on the server. A mobile client should pass this parameter, to avoid triggering a test notification for other clients. type: string example: "111222" responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" "400": description: | Bad request. content: application/json: schema: oneOf: - $ref: "#/components/schemas/InvalidPushDeviceTokenError" - $ref: "#/components/schemas/InvalidRemotePushDeviceTokenError" /user_topics: post: operationId: update-user-topic summary: Update personal preferences for a topic tags: ["channels"] description: | This endpoint is used to update the personal preferences for a topic, such as the topic's visibility policy, which is used to implement [mute a topic](/help/mute-a-topic) and related features. This endpoint can be used to update the visibility policy for the single channel and topic pair indicated by the parameters for a user. **Changes**: New in Zulip 7.0 (feature level 170). Previously, toggling whether a topic was muted or unmuted was managed by the [PATCH /users/me/subscriptions/muted_topics](/api/mute-topic) endpoint. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: stream_id: description: | The ID of the channel to access. type: integer example: 1 topic: description: | The topic for which the personal preferences needs to be updated. Note that the request will succeed regardless of whether any messages have been sent to the specified topic. Clients should use the `max_topic_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum topic length. type: string example: dinner visibility_policy: description: | Controls which visibility policy to set. - 0 = None. Removes the visibility policy previously set for the topic. - 1 = Muted. [Mutes the topic](/help/mute-a-topic) in a channel. - 2 = Unmuted. [Unmutes the topic](/help/mute-a-topic) in a muted channel. - 3 = Followed. [Follows the topic](/help/follow-a-topic). In an unmuted channel, a topic visibility policy of unmuted will have the same effect as the "None" visibility policy. **Changes**: In Zulip 7.0 (feature level 219), added followed as a visibility policy option. type: integer enum: - 0 - 1 - 2 - 3 example: 1 required: - stream_id - topic - visibility_policy encoding: stream_id: contentType: application/json visibility_policy: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" /users/me/muted_users/{muted_user_id}: post: operationId: mute-user summary: Mute a user tags: ["users"] description: | [Mute a user](/help/mute-a-user) from the perspective of the requesting user. Messages sent by muted users will be automatically marked as read and hidden for the user who muted them. Muted users should be implemented by clients as follows: - The server will immediately mark all messages sent by the muted user as read. This will automatically clear any existing mobile push notifications related to the muted user. - The server will mark any new messages sent by the muted user as read for the requesting user's account, which prevents all email and mobile push notifications. - Clients should exclude muted users from presence lists or other UI for viewing or composing one-on-one direct messages. One-on-one direct messages sent by muted users should be hidden everywhere in the Zulip UI. - Channel messages and group direct messages sent by the muted user should avoid displaying the content and name/avatar, but should display that N messages by a muted user were hidden (so that it is possible to interpret the messages by other users who are talking with the muted user). - Group direct message conversations including the muted user should display muted users as "Muted user", rather than showing their name, in lists of such conversations, along with using a blank grey avatar where avatars are displayed. - Administrative/settings UI elements for showing "All users that exist on this channel or realm", e.g. for organization administration or showing channel subscribers, should display the user's name as normal. **Changes**: New in Zulip 4.0 (feature level 48). parameters: - $ref: "#/components/parameters/MutedUserId" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Cannot mute self", "result": "error", } description: | An example JSON response for when the user ID is the current user's ID: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "No such user", "result": "error", } description: | An example JSON response for when the user is nonexistent or inaccessible: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "User already muted", "result": "error", } description: | An example JSON response for when the user is already muted: delete: operationId: unmute-user summary: Unmute a user tags: ["users"] description: | [Unmute a user](/help/mute-a-user#see-your-list-of-muted-users) from the perspective of the requesting user. **Changes**: New in Zulip 4.0 (feature level 48). parameters: - $ref: "#/components/parameters/MutedUserId" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "No such user", "result": "error", } description: | An example JSON response for when the user is nonexistent or inaccessible: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "User is not muted", "result": "error", } description: | An example JSON response for when the user is not previously muted: /users/me/apns_device_token: post: operationId: add-apns-token summary: Add an APNs device token tags: ["users"] description: | This endpoint adds an APNs device token to register for iOS push notifications. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: | The token provided by the device. type: string example: apple-tokenbb appid: description: | The ID of the Zulip app that is making the request. **Changes**: In Zulip 8.0 (feature level 223), this parameter was made required. Previously, if it was unspecified, the server would use a default value (based on the `ZULIP_IOS_APP_ID` server setting, which defaulted to `"org.zulip.Zulip"`). type: string example: org.zulip.Zulip required: - token - appid responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when the token's length is invalid or it is empty: example: { "result": "error", "msg": "Empty or invalid length token", "code": "BAD_REQUEST", } - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid APNS token", "code": "BAD_REQUEST", } description: | A typical failed JSON response for when the APNs token is invalid: delete: operationId: remove-apns-token summary: Remove an APNs device token tags: ["users"] description: | This endpoint removes an APNs device token for iOS push notifications. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: | The token provided by the device. type: string example: apple-tokenbb required: - token responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when the token's length is invalid or it is empty: example: { "result": "error", "msg": "Empty or invalid length token", "code": "BAD_REQUEST", } - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Token does not exist", "code": "BAD_REQUEST", } description: | A typical failed JSON response for when the token does not exist: /users/me/android_gcm_reg_id: post: operationId: add-fcm-token summary: Add an FCM registration token tags: ["users"] description: | This endpoint adds an FCM registration token for push notifications. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: | The token provided by the device. type: string example: android-token required: - token responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when the token's length is invalid or is empty: example: { "result": "error", "msg": "Empty or invalid length token", "code": "BAD_REQUEST", } delete: operationId: remove-fcm-token summary: Remove an FCM registration token tags: ["users"] description: | This endpoint removes an FCM registration token for push notifications. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: | The token provided by the device. type: string example: android-token required: - token responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/CodedError" - description: | A typical failed JSON response for when the token's length is invalid or is empty: example: { "result": "error", "msg": "Empty or invalid length token", "code": "BAD_REQUEST", } - allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Token does not exist", "code": "BAD_REQUEST", } description: | A typical failed JSON response for when the token does not exist: /users/{user_id}/subscriptions/{stream_id}: get: operationId: get-subscription-status summary: Get subscription status tags: ["channels"] description: | Check whether a user is subscribed to a channel. **Changes**: New in Zulip 3.0 (feature level 12). parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} is_subscribed: type: boolean description: | Whether the user is subscribed to the channel. example: {"msg": "", "result": "success", "is_subscribed": false} /realm/emoji/{emoji_name}: post: operationId: upload-custom-emoji summary: Upload custom emoji tags: ["server_and_organizations"] description: | This endpoint is used to upload a custom emoji for use in the user's organization. Access to this endpoint depends on the [organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji). x-parameter-description: | As described above, the image file to upload must be provided in the request's body. ## Maximum file size The maximum file size for uploads can be configured by the administrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB` in the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults to 5MB. [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings parameters: - name: emoji_name required: true in: path description: | The name that should be associated with the uploaded emoji image/gif. The emoji name can only contain letters, numbers, dashes, and spaces. Upper and lower case letters are treated the same, and underscores (\_) are treated the same as spaces (consistent with how the Zulip UI handles emoji). schema: type: string example: smile requestBody: content: multipart/form-data: schema: type: object properties: filename: type: string format: binary example: /path/to/img.png responses: "200": $ref: "#/components/responses/SimpleSuccess" delete: operationId: deactivate-custom-emoji summary: Deactivate custom emoji tags: ["server_and_organizations"] description: | [Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from the user's organization. Users can only deactivate custom emoji that they added themselves except for organization administrators, who can deactivate any custom emoji. Note that deactivated emoji will still be visible in old messages, reactions, user statuses and channel descriptions. **Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an HTTP status code of 400 when the emoji did not exist, instead of 404. parameters: - name: emoji_name required: true in: path description: | The name of the custom emoji to deactivate. schema: type: string example: green_tick responses: "200": $ref: "#/components/responses/SimpleSuccess" "404": description: Not Found. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - description: | An example JSON response for when no emoji exists with the provided name: example: { "code": "BAD_REQUEST", "result": "error", "msg": "Emoji 'green_tick' does not exist", } /realm/emoji: get: operationId: get-custom-emoji summary: Get all custom emoji tags: ["server_and_organizations"] description: | Get all the custom emoji in the user's organization. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} emoji: type: object description: | An object that contains `emoji` objects, each identified with their emoji ID as the key. additionalProperties: $ref: "#/components/schemas/RealmEmoji" example: { "result": "success", "msg": "", "emoji": { "1": { "id": "1", "name": "green_tick", "source_url": "/user_avatars/1/emoji/images/1.png", "deactivated": false, "author_id": 5, }, }, } /realm/presence: get: operationId: get-presence summary: Get presence of all users tags: ["server_and_organizations"] description: | Get the presence information of all the users in an organization. If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is set to `true`, presence information of only accessible users are returned. See [Zulip's developer documentation][subsystems-presence] for details on the data model for presence in Zulip. [subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} server_timestamp: type: number description: | The time when the server fetched the `presences` data included in the response. presences: type: object description: | A dictionary where each entry describes the presence details of a user in the Zulip organization. additionalProperties: type: object description: | `{user_email}`: Object containing the details of a user's presence. The object's key is the user's Zulip API email. additionalProperties: $ref: "#/components/schemas/LegacyPresenceFormat" example: { "msg": "", "presences": { "iago@zulip.com": { "website": { "client": "website", "pushable": false, "status": "active", "timestamp": 1656958485, }, "aggregated": { "client": "website", "status": "active", "timestamp": 1656958485, }, }, }, "result": "success", "server_timestamp": 1656958539.6287155, } /realm/profile_fields: get: operationId: get-custom-profile-fields summary: Get all custom profile fields tags: ["server_and_organizations"] description: | Get all the [custom profile fields](/help/custom-profile-fields) configured for the user's organization. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} custom_fields: type: array description: | An array containing all the custom profile fields defined in this Zulip organization. items: $ref: "#/components/schemas/CustomProfileField" example: { "result": "success", "msg": "", "custom_fields": [ { "id": 1, "name": "Phone number", "type": 1, "hint": "", "field_data": "", "order": 1, "required": true, "editable_by_user": false, }, { "id": 2, "name": "Biography", "type": 2, "hint": "What are you known for?", "field_data": "", "order": 2, "required": true, "editable_by_user": true, }, { "id": 3, "name": "Favorite food", "type": 1, "hint": "Or drink, if you'd prefer", "field_data": "", "order": 3, "required": false, "editable_by_user": true, }, { "id": 4, "name": "Favorite editor", "type": 3, "hint": "", "field_data": '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}', "order": 4, "display_in_profile_summary": true, "required": true, "editable_by_user": true, }, { "id": 5, "name": "Birthday", "type": 4, "hint": "", "field_data": "", "order": 5, "required": false, "editable_by_user": false, }, { "id": 6, "name": "Favorite website", "type": 5, "hint": "Or your personal blog's URL", "field_data": "", "order": 6, "display_in_profile_summary": true, "required": false, "editable_by_user": true, }, { "id": 7, "name": "Mentor", "type": 6, "hint": "", "field_data": "", "order": 7, "required": true, "editable_by_user": false, }, { "id": 8, "name": "GitHub", "type": 7, "hint": "Enter your GitHub username", "field_data": '{"subtype":"github"}', "order": 8, "required": true, "editable_by_user": true, }, { "id": 9, "name": "Pronouns", "type": 8, "hint": "What pronouns should people use to refer to you?", "order": 9, "required": false, "editable_by_user": true, }, ], } patch: operationId: reorder-custom-profile-fields summary: Reorder custom profile fields tags: ["server_and_organizations"] description: | Reorder the custom profile fields in the user's organization. Custom profile fields are displayed in Zulip UI widgets in order; this endpoint allows administrative settings UI to change the field ordering. This endpoint is used to implement the dragging feature described in the [custom profile fields documentation](/help/custom-profile-fields). x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: order: description: | A list of the IDs of all the custom profile fields defined in this organization, in the desired new order. type: array items: type: integer example: [11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1] required: - order encoding: order: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" post: operationId: create-custom-profile-field summary: Create a custom profile field tags: ["server_and_organizations"] description: | [Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization. x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: description: | The name of the custom profile field, which will appear both in user-facing settings UI for configuring custom profile fields and in UI displaying a user's profile. type: string example: "Favorite programming language" hint: description: | The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields. type: string example: "Your favorite programming language." field_type: description: | The field type can be any of the supported custom profile field types. See the [custom profile fields documentation](/help/custom-profile-fields) for more details on what each type means. - **1**: Short text - **2**: Long text - **3**: List of options - **4**: Date picker - **5**: Link - **6**: Person picker - **7**: External account - **8**: Pronouns **Changes**: Field type `8` added in Zulip 6.0 (feature level 151). type: integer example: 3 field_data: description: | Field types 3 (List of options) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (List of options), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option. The interface for field type 7 is not yet stabilized. type: object example: { "python": {"text": "Python", "order": "1"}, "java": {"text": "Java", "order": "2"}, } display_in_profile_summary: description: | Whether clients should display this profile field in a summary section of a user's profile (or in a more easily accessible "small profile"). At most 2 profile fields may have this property be true in a given organization. The "Long text" [profile field types][profile-field-types] profile field types cannot be selected to be displayed in profile summaries. The "Person picker" profile field is also not supported, but that is likely to be temporary. [profile-field-types]: /help/custom-profile-fields#profile-field-types **Changes**: New in Zulip 6.0 (feature level 146). type: boolean example: true required: description: | Whether an organization administrator has configured this profile field as required. Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field. **Changes**: New in Zulip 9.0 (feature level 244). type: boolean example: true editable_by_user: description: | Whether regular users can edit this profile field on their own account. Note that organization administrators can edit custom profile fields for any user regardless of this setting. **Changes**: New in Zulip 10.0 (feature level 296). type: boolean example: true required: - field_type encoding: field_type: contentType: application/json field_data: contentType: application/json display_in_profile_summary: contentType: application/json required: contentType: application/json editable_by_user: contentType: application/json responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: | The ID for the custom profile field. example: {"result": "success", "msg": "", "id": 9} /realm/user_settings_defaults: patch: operationId: update-realm-user-settings-defaults summary: Update realm-level defaults of user settings tags: ["server_and_organizations"] x-requires-administrator: true description: | Change the [default values of settings][new-user-defaults] for new users joining the organization. Essentially all [personal preference settings](/api/update-settings) are supported. This feature can be invaluable for customizing Zulip's default settings for notifications or UI to be appropriate for how the organization is using Zulip. (Note that this only supports personal preference settings, like when to send push notifications or what emoji set to use, not profile or identity settings that naturally should be different for each user). Note that this endpoint cannot, at present, be used to modify settings for existing users in any way. **Changes**: New in Zulip 5.0 (feature level 96). If any parameters sent in the request are not supported by this endpoint, an [`ignored_parameters_unsupported`][ignored-parameters] array will be returned in the JSON success response. [new-user-defaults]: /help/configure-default-new-user-settings [ignored-parameters]: /api/rest-error-handling#ignored-parameters x-curl-examples-parameters: oneOf: - type: include parameters: enum: - left_side_userlist - emojiset requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: dense_mode: description: | This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip. type: boolean example: true starred_message_counts: description: | Whether clients should display the [number of starred messages](/help/star-a-message#display-the-number-of-starred-messages). type: boolean example: true receives_typing_notifications: description: | Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. type: boolean example: true fluid_layout_width: description: | Whether to use the [maximum available screen width](/help/enable-full-width-display) for the web app's center panel (message feed, recent conversations) on wide screens. type: boolean example: true high_contrast_mode: description: | This setting is reserved for use to control variations in Zulip's design to help visually impaired users. type: boolean example: true web_mark_read_on_scroll_policy: description: | Whether or not to mark messages as read when the user scrolls through their feed. - 1 - Always - 2 - Only in conversation views - 3 - Never **Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read. type: integer enum: - 1 - 2 - 3 example: 1 web_channel_default_view: description: | Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed **Changes**: New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior. type: integer enum: - 1 - 2 example: 1 web_font_size_px: description: | User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. type: integer example: 14 web_line_height_percent: description: | User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. type: integer example: 122 color_scheme: description: | Controls which [color theme](/help/dark-theme) to use. - 1 - Automatic - 2 - Dark theme - 3 - Light theme Automatic detection is implementing using the standard `prefers-color-scheme` media query. type: integer enum: - 1 - 2 - 3 example: 1 enable_drafts_synchronization: description: | A boolean parameter to control whether synchronizing drafts is enabled for the user. When synchronization is disabled, all drafts stored in the server will be automatically deleted from the server. This does not do anything (like sending events) to delete local copies of drafts stored in clients. type: boolean example: true translate_emoticons: description: | Whether to [translate emoticons to emoji](/help/configure-emoticon-translations) in messages the user sends. type: boolean example: true display_emoji_reaction_users: description: | Whether to display the names of reacting users on a message. When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled. **Changes**: New in Zulip 6.0 (feature level 125). type: boolean example: false web_home_view: description: | The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent_topics" - Recent conversations view - "inbox" - Inbox view - "all_messages" - Combined feed view **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `default_view`, which was new in Zulip 4.0 (feature level 42). type: string example: all_messages web_escape_navigates_to_home_view: description: | Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107). type: boolean example: true left_side_userlist: description: | Whether the users list on left sidebar in narrow windows. This feature is not heavily used and is likely to be reworked. type: boolean example: true emojiset: description: | The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons), used to display emoji to the user everywhere they appear in the UI. - "google" - Google - "twitter" - Twitter - "text" - Plain text - "google-blob" - Google blobs type: string example: "google" demote_inactive_streams: description: | Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar. - 1 - Automatic - 2 - Always - 3 - Never type: integer enum: - 1 - 2 - 3 example: 1 user_list_style: description: | The style selected by the user for the right sidebar user list. - 1 - Compact - 2 - With status - 3 - With avatar and status **Changes**: New in Zulip 6.0 (feature level 141). type: integer enum: - 1 - 2 - 3 example: 1 web_animate_image_previews: description: | Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images always used to play in the message feed by default. This setting controls this behaviour. type: string enum: - always - on_hover - never example: on_hover web_stream_unreads_count_display_policy: description: | Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). type: integer enum: - 1 - 2 - 3 example: 2 enable_stream_desktop_notifications: description: | Enable visual desktop notifications for channel messages. type: boolean example: true enable_stream_email_notifications: description: | Enable email notifications for channel messages. type: boolean example: true enable_stream_push_notifications: description: | Enable mobile notifications for channel messages. type: boolean example: true enable_stream_audible_notifications: description: | Enable audible desktop notifications for channel messages. type: boolean example: true notification_sound: description: | Notification sound name. type: string example: ding enable_desktop_notifications: description: | Enable visual desktop notifications for direct messages and @-mentions. type: boolean example: true enable_sounds: description: | Enable audible desktop notifications for direct messages and @-mentions. type: boolean example: true enable_followed_topic_desktop_notifications: description: | Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true enable_followed_topic_email_notifications: description: | Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true enable_followed_topic_push_notifications: description: | Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: false enable_followed_topic_audible_notifications: description: | Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: false email_notifications_batching_period_seconds: description: | The duration (in seconds) for which the server should wait to batch email notifications before sending them. type: integer example: 120 enable_offline_email_notifications: description: | Enable email notifications for direct messages and @-mentions received when the user is offline. type: boolean example: true enable_offline_push_notifications: description: | Enable mobile notification for direct messages and @-mentions received when the user is offline. type: boolean example: true enable_online_push_notifications: description: | Enable mobile notification for direct messages and @-mentions received when the user is online. type: boolean example: true enable_digest_emails: description: | Enable digest emails when the user is away. type: boolean example: true message_content_in_email_notifications: description: | Include the message's content in email notifications for new messages. type: boolean example: true pm_content_in_desktop_notifications: description: | Include content of direct messages in desktop notifications. type: boolean example: true wildcard_mentions_notify: description: | Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. type: boolean example: true enable_followed_topic_wildcard_mentions_notify: description: | Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true desktop_icon_count_display: description: | Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. type: integer enum: - 1 - 2 - 3 - 4 example: 1 realm_name_in_email_notifications_policy: description: | Whether to [include organization name in subject of message notification emails](/help/email-notifications#include-organization-name-in-subject-line). - 1 - Automatic - 2 - Always - 3 - Never **Changes**: New in Zulip 7.0 (feature level 168), replacing the previous `realm_name_in_notifications` boolean; `true` corresponded to `Always`, and `false` to `Never`. type: integer enum: - 1 - 2 - 3 example: 1 automatically_follow_topics_policy: description: | Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_unmute_topics_in_muted_streams_policy: description: | Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_follow_topics_where_mentioned: description: | Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). type: boolean example: true presence_enabled: description: | Display the presence status to other users when online. type: boolean example: true enter_sends: description: | Whether pressing Enter in the compose box sends a message (or saves a message edit). type: boolean example: true twenty_four_hour_time: description: | Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). **Changes**: New in Zulip 5.0 (feature level 99). Previously, this default was edited using the `default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint. type: boolean example: true send_private_typing_notifications: description: | Whether [typing notifications](/help/typing-notifications) be sent when composing direct messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true send_stream_typing_notifications: description: | Whether [typing notifications](/help/typing-notifications) be sent when composing channel messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true send_read_receipts: description: | Whether other users are allowed to see whether you've read messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true email_address_visibility: description: | The [policy][permission-level] for [which other users][help-email-visibility] in this organization can see the user's real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility type: integer enum: - 1 - 2 - 3 - 4 - 5 example: 1 web_navigate_to_sent_message: description: | Web/desktop app setting for whether the user's view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. type: boolean example: true encoding: dense_mode: contentType: application/json starred_message_counts: contentType: application/json receives_typing_notifications: contentType: application/json fluid_layout_width: contentType: application/json high_contrast_mode: contentType: application/json web_mark_read_on_scroll_policy: contentType: application/json web_channel_default_view: contentType: application/json web_font_size_px: contentType: application/json web_line_height_percent: contentType: application/json color_scheme: contentType: application/json enable_drafts_synchronization: contentType: application/json translate_emoticons: contentType: application/json display_emoji_reaction_users: contentType: application/json web_escape_navigates_to_home_view: contentType: application/json left_side_userlist: contentType: application/json demote_inactive_streams: contentType: application/json user_list_style: contentType: application/json web_stream_unreads_count_display_policy: contentType: application/json enable_stream_desktop_notifications: contentType: application/json enable_stream_email_notifications: contentType: application/json enable_stream_push_notifications: contentType: application/json enable_stream_audible_notifications: contentType: application/json enable_desktop_notifications: contentType: application/json enable_sounds: contentType: application/json enable_followed_topic_desktop_notifications: contentType: application/json enable_followed_topic_email_notifications: contentType: application/json enable_followed_topic_push_notifications: contentType: application/json enable_followed_topic_audible_notifications: contentType: application/json email_notifications_batching_period_seconds: contentType: application/json enable_offline_email_notifications: contentType: application/json enable_offline_push_notifications: contentType: application/json enable_online_push_notifications: contentType: application/json enable_digest_emails: contentType: application/json message_content_in_email_notifications: contentType: application/json pm_content_in_desktop_notifications: contentType: application/json wildcard_mentions_notify: contentType: application/json enable_followed_topic_wildcard_mentions_notify: contentType: application/json desktop_icon_count_display: contentType: application/json realm_name_in_email_notifications_policy: contentType: application/json automatically_follow_topics_policy: contentType: application/json automatically_unmute_topics_in_muted_streams_policy: contentType: application/json automatically_follow_topics_where_mentioned: contentType: application/json presence_enabled: contentType: application/json enter_sends: contentType: application/json twenty_four_hour_time: contentType: application/json send_private_typing_notifications: contentType: application/json send_stream_typing_notifications: contentType: application/json send_read_receipts: contentType: application/json email_address_visibility: contentType: application/json web_navigate_to_sent_message: contentType: application/json responses: "200": $ref: "#/components/responses/SuccessIgnoredParameters" /users/me/subscriptions/properties: post: operationId: update-subscription-settings summary: Update subscription settings tags: ["channels"] description: | This endpoint is used to update the user's personal settings for the channels they are subscribed to, including muting, color, pinning, and per-channel notification settings. **Changes**: Prior to Zulip 5.0 (feature level 111), response object included the `subscription_data` in the request. The endpoint now returns the more ergonomic [`ignored_parameters_unsupported`][ignored-parameters] array instead. [ignored-parameters]: /api/rest-error-handling#ignored-parameters requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: subscription_data: description: | A list of objects that describe the changes that should be applied in each subscription. Each object represents a subscription, and must have a `stream_id` key that identifies the channel, as well as the `property` being modified and its new `value`. type: array items: type: object additionalProperties: false properties: stream_id: type: integer description: | The unique ID of a channel. property: type: string enum: - color - is_muted - in_home_view - pin_to_top - desktop_notifications - audible_notifications - push_notifications - email_notifications - wildcard_mentions_notify description: | One of the channel properties described below: - `"color"`: The hex value of the user's display color for the channel. - `"is_muted"`: Whether the channel is [muted](/help/mute-a-channel).I am:
\n+0-11-23-456-7890
", }, "8": {"value": "zulipbot"}, "3": { "rendered_value": "Dark chocolate
", "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-by-email summary: Update a user by email tags: ["users"] x-requires-administrator: true description: | Administrative endpoint to update the details of another user in the organization by their email address. Works the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their real email address. The requester needs to have permission to view the target user's real email address, subject to the user's email address visibility setting. Otherwise, the dummy address of the format `user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{email}`. **Changes**: New in Zulip 10.0 (feature level 313). parameters: - name: email in: path required: true description: | The email address of the user, specified following the same rules as [`GET /users/{email}`](/api/get-user-by-email). schema: type: string example: hamlet@zulip.com requestBody: $ref: "#/components/requestBodies/UpdateUser" 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: /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": "I am:
\n+0-11-23-456-7890
", }, "8": {"value": "zulipbot"}, "3": { "rendered_value": "Dark chocolate
", "value": "Dark chocolate", }, }, "user_id": 10, "is_bot": false, "bot_type": null, "timezone": "", "is_admin": false, "is_owner": false, "is_billing_admin": false, "role": 400, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com", "delivery_email": null, }, } patch: operationId: update-user summary: Update a user tags: ["users"] x-requires-administrator: true description: | Administrative endpoint to update the details of another user in the organization. Supports everything an administrator can do to edit details of another user's account, including editing full name, [role](/help/roles-and-permissions), and [custom profile fields](/help/custom-profile-fields). parameters: - $ref: "#/components/parameters/UserId" requestBody: $ref: "#/components/requestBodies/UpdateUser" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Guests cannot be organization administrators", "code": "BAD_REQUEST", } description: | A typical unsuccessful JSON response: delete: operationId: deactivate-user summary: Deactivate a user tags: ["users"] x-requires-administrator: true description: | [Deactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. parameters: - $ref: "#/components/parameters/UserId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: deactivation_notification_comment: description: | If not `null`, requests that the deactivated user receive a notification email about their account deactivation. If not `""`, encodes custom text written by the administrator to be included in the notification email. **Changes**: New in Zulip 5.0 (feature level 135). type: string example: | Farewell! responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Cannot deactivate the only organization owner", "result": "error", } description: | An example JSON error response when attempting to deactivate the only organization owner in an organization: /realm/linkifiers: get: operationId: get-linkifiers summary: Get linkifiers tags: ["server_and_organizations"] description: | List all of an organization's configured [linkifiers](/help/add-a-custom-linkifier), regular expression patterns that are automatically linkified when they appear in messages and topics. **Changes**: New in Zulip 4.0 (feature level 54). On older versions, a similar `GET /realm/filters` endpoint was available with each entry in a `[pattern, url_format, id]` tuple format. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} linkifiers: type: array description: | An ordered array of objects, where each object describes a linkifier. Clients should always process linkifiers in the order given; this is important if the realm has linkifiers with overlapping patterns. The order can be modified using [`PATCH /realm/linkifiers`](/api/reorder-linkifiers). items: type: object additionalProperties: false properties: pattern: type: string description: | The string regex pattern which represents the pattern that should be linkified by this linkifier. url_template: type: string description: | The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template to be used for linkifying matches. **Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`, which contained a URL format string. id: type: integer description: | The ID of the linkifier. example: { "msg": "", "linkifiers": [ { "pattern": "#(?PThe Zulip development environment default organization. It's great for testing!
", "realm_web_public_access_enabled": false, "result": "success", "external_authentication_methods": [ { "name": "saml:idp_name", "display_name": "SAML", "display_icon": null, "login_url": "/accounts/login/social/saml/idp_name", "signup_url": "/accounts/register/social/saml/idp_name", }, { "name": "google", "display_name": "Google", "display_icon": "/static/images/authentication_backends/googl_e-icon.png", "login_url": "/accounts/login/social/google", "signup_url": "/accounts/register/social/google", }, { "name": "github", "display_name": "GitHub", "display_icon": "/static/images/authentication_backends/github-icon.png", "login_url": "/accounts/login/social/github", "signup_url": "/accounts/register/social/github", }, ], } /settings: patch: operationId: update-settings summary: Update settings tags: ["users"] description: | This endpoint is used to edit the current user's settings. **Changes**: Prior to Zulip 5.0 (feature level 80), this endpoint only supported the `full_name`, `email`, `old_password`, and `new_password` parameters. Notification settings were managed by `PATCH /settings/notifications`, and all other settings by `PATCH /settings/display`. The feature level 80 migration to merge these endpoints did not change how request parameters are encoded. However, it did change the handling of any invalid parameters present in a request (see feature level 78 change below). As of feature level 80, the `PATCH /settings/display` and `PATCH /settings/notifications` endpoints are deprecated aliases for this endpoint for backwards-compatibility, and will be removed once clients have migrated to use this endpoint. Prior to Zulip 5.0 (feature level 78), this endpoint indicated which parameters it had processed by including in the response object `"key": value` entries for values successfully changed by the request. That was replaced by the more ergonomic [`ignored_parameters_unsupported`][ignored-parameters] array. The `PATCH /settings/notifications` and `PATCH /settings/display` endpoints also had this behavior of indicating processed parameters before they became aliases of this endpoint in Zulip 5.0 (see feature level 80 change above). Before feature level 78, request parameters that were not supported (or were unchanged) were silently ignored. [ignored-parameters]: /api/rest-error-handling#ignored-parameters x-curl-examples-parameters: oneOf: - type: include parameters: enum: - left_side_userlist - emojiset requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: full_name: description: | A new display name for the user. type: string example: NewName email: description: | Asks the server to initiate a confirmation sequence to change the user's email address to the indicated value. The user will need to demonstrate control of the new email address by clicking a confirmation link sent to that address. type: string example: newname@example.com old_password: description: | The user's old Zulip password (or LDAP password, if LDAP authentication is in use). Required only when sending the `new_password` parameter. type: string example: old12345 new_password: description: | The user's new Zulip password (or LDAP password, if LDAP authentication is in use). The `old_password` parameter must be included in the request. type: string example: new12345 twenty_four_hour_time: description: | Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true dense_mode: description: | This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true web_mark_read_on_scroll_policy: description: | Whether or not to mark messages as read when the user scrolls through their feed. - 1 - Always - 2 - Only in conversation views - 3 - Never **Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read. type: integer enum: - 1 - 2 - 3 example: 1 web_channel_default_view: description: | Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed **Changes**: New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior. type: integer enum: - 1 - 2 example: 1 starred_message_counts: description: | Whether clients should display the [number of starred messages](/help/star-a-message#display-the-number-of-starred-messages). **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true receives_typing_notifications: description: | Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. By default, this is set to true, enabling user to receive typing notifications from other users. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. type: boolean example: true fluid_layout_width: description: | Whether to use the [maximum available screen width](/help/enable-full-width-display) for the web app's center panel (message feed, recent conversations) on wide screens. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true high_contrast_mode: description: | This setting is reserved for use to control variations in Zulip's design to help visually impaired users. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true web_font_size_px: description: | User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. type: integer example: 14 web_line_height_percent: description: | User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. type: integer example: 122 color_scheme: description: | Controls which [color theme](/help/dark-theme) to use. - 1 - Automatic - 2 - Dark theme - 3 - Light theme Automatic detection is implementing using the standard `prefers-color-scheme` media query. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: integer enum: - 1 - 2 - 3 example: 1 enable_drafts_synchronization: description: | A boolean parameter to control whether synchronizing drafts is enabled for the user. When synchronization is disabled, all drafts stored in the server will be automatically deleted from the server. This does not do anything (like sending events) to delete local copies of drafts stored in clients. **Changes**: New in Zulip 5.0 (feature level 87). type: boolean example: true translate_emoticons: description: | Whether to [translate emoticons to emoji](/help/configure-emoticon-translations) in messages the user sends. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true display_emoji_reaction_users: description: | Whether to display the names of reacting users on a message. When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled. **Changes**: New in Zulip 6.0 (feature level 125). type: boolean example: false default_language: description: | What [default language](/help/change-your-language) to use for the account. This controls both the Zulip UI as well as email notifications sent to the user. The value needs to be a standard language code that the Zulip server has translation data for; for example, `"en"` for English or `"de"` for German. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63). type: string example: en web_home_view: description: | The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent_topics" - Recent conversations view - "inbox" - Inbox view - "all_messages" - Combined feed view **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `default_view`, which was new in Zulip 4.0 (feature level 42). Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). type: string example: all_messages web_escape_navigates_to_home_view: description: | Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107). type: boolean example: true left_side_userlist: description: | Whether the users list on left sidebar in narrow windows. This feature is not heavily used and is likely to be reworked. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: boolean example: true emojiset: description: | The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons), used to display emoji to the user everywhere they appear in the UI. - "google" - Google modern - "google-blob" - Google classic - "twitter" - Twitter - "text" - Plain text **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). type: string example: "google" demote_inactive_streams: description: | Whether to [demote inactive channels](/help/manage-inactive-channels) in the left sidebar. - 1 - Automatic - 2 - Always - 3 - Never **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. type: integer enum: - 1 - 2 - 3 example: 1 user_list_style: description: | The style selected by the user for the right sidebar user list. - 1 - Compact - 2 - With status - 3 - With avatar and status **Changes**: New in Zulip 6.0 (feature level 141). type: integer enum: - 1 - 2 - 3 example: 1 web_animate_image_previews: description: | Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). type: string enum: - always - on_hover - never example: on_hover web_stream_unreads_count_display_policy: description: | Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). type: integer enum: - 1 - 2 - 3 example: 2 timezone: description: | The IANA identifier of the user's [configured time zone](/help/change-your-timezone). **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). type: string example: "Asia/Kolkata" enable_stream_desktop_notifications: description: | Enable visual desktop notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_stream_email_notifications: description: | Enable email notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_stream_push_notifications: description: | Enable mobile notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_stream_audible_notifications: description: | Enable audible desktop notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true notification_sound: description: | Notification sound name. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63). type: string example: ding enable_desktop_notifications: description: | Enable visual desktop notifications for direct messages and @-mentions. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_sounds: description: | Enable audible desktop notifications for direct messages and @-mentions. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true email_notifications_batching_period_seconds: description: | The duration (in seconds) for which the server should wait to batch email notifications before sending them. **Changes**: New in Zulip 5.0 (feature level 82) type: integer example: 120 enable_offline_email_notifications: description: | Enable email notifications for direct messages and @-mentions received when the user is offline. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_offline_push_notifications: description: | Enable mobile notification for direct messages and @-mentions received when the user is offline. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_online_push_notifications: description: | Enable mobile notification for direct messages and @-mentions received when the user is online. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_followed_topic_desktop_notifications: description: | Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true enable_followed_topic_email_notifications: description: | Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true enable_followed_topic_push_notifications: description: | Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: false enable_followed_topic_audible_notifications: description: | Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: false enable_digest_emails: description: | Enable digest emails when the user is away. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_marketing_emails: description: | Enable marketing emails. Has no function outside Zulip Cloud. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_login_emails: description: | Enable email notifications for new logins to account. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true message_content_in_email_notifications: description: | Include the message's content in email notifications for new messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true pm_content_in_desktop_notifications: description: | Include content of direct messages in desktop notifications. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true wildcard_mentions_notify: description: | Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enable_followed_topic_wildcard_mentions_notify: description: | Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). type: boolean example: true desktop_icon_count_display: description: | Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: integer enum: - 1 - 2 - 3 - 4 example: 1 realm_name_in_email_notifications_policy: description: | Whether to [include organization name in subject of message notification emails](/help/email-notifications#include-organization-name-in-subject-line). - 1 - Automatic - 2 - Always - 3 - Never **Changes**: New in Zulip 7.0 (feature level 168), replacing the previous `realm_name_in_notifications` boolean; `true` corresponded to `Always`, and `false` to `Never`. Before Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications` setting was managed by the `PATCH /settings/notifications` endpoint. type: integer enum: - 1 - 2 - 3 example: 1 automatically_follow_topics_policy: description: | Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_unmute_topics_in_muted_streams_policy: description: | Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_follow_topics_where_mentioned: description: | Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). type: boolean example: true presence_enabled: description: | Display the presence status to other users when online. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. type: boolean example: true enter_sends: description: | Whether pressing Enter in the compose box sends a message (or saves a message edit). **Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by the `POST /users/me/enter-sends` endpoint, with the same parameter format. type: boolean example: true send_private_typing_notifications: description: | Whether [typing notifications](/help/typing-notifications) be sent when composing direct messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true send_stream_typing_notifications: description: | Whether [typing notifications](/help/typing-notifications) be sent when composing channel messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true send_read_receipts: description: | Whether other users are allowed to see whether you've read messages. **Changes**: New in Zulip 5.0 (feature level 105). type: boolean example: true allow_private_data_export: description: | Whether organization administrators are allowed to export your private data. **Changes**: New in Zulip 10.0 (feature level 293). type: boolean example: true email_address_visibility: description: | The [policy][permission-level] this user has selected for [which other users][help-email-visibility] in this organization can see their real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility type: integer enum: - 1 - 2 - 3 - 4 - 5 example: 1 web_navigate_to_sent_message: description: | Web/desktop app setting for whether the user's view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. type: boolean example: true encoding: twenty_four_hour_time: contentType: application/json dense_mode: contentType: application/json web_mark_read_on_scroll_policy: contentType: application/json web_channel_default_view: contentType: application/json starred_message_counts: contentType: application/json receives_typing_notifications: contentType: application/json fluid_layout_width: contentType: application/json high_contrast_mode: contentType: application/json web_font_size_px: contentType: application/json web_line_height_percent: contentType: application/json color_scheme: contentType: application/json enable_drafts_synchronization: contentType: application/json translate_emoticons: contentType: application/json display_emoji_reaction_users: contentType: application/json web_escape_navigates_to_home_view: contentType: application/json left_side_userlist: contentType: application/json demote_inactive_streams: contentType: application/json user_list_style: contentType: application/json web_stream_unreads_count_display_policy: contentType: application/json enable_stream_desktop_notifications: contentType: application/json enable_stream_email_notifications: contentType: application/json enable_stream_push_notifications: contentType: application/json enable_stream_audible_notifications: contentType: application/json enable_desktop_notifications: contentType: application/json enable_sounds: contentType: application/json email_notifications_batching_period_seconds: contentType: application/json enable_offline_email_notifications: contentType: application/json enable_offline_push_notifications: contentType: application/json enable_online_push_notifications: contentType: application/json enable_followed_topic_desktop_notifications: contentType: application/json enable_followed_topic_email_notifications: contentType: application/json enable_followed_topic_push_notifications: contentType: application/json enable_followed_topic_audible_notifications: contentType: application/json enable_digest_emails: contentType: application/json enable_marketing_emails: contentType: application/json enable_login_emails: contentType: application/json message_content_in_email_notifications: contentType: application/json pm_content_in_desktop_notifications: contentType: application/json wildcard_mentions_notify: contentType: application/json enable_followed_topic_wildcard_mentions_notify: contentType: application/json desktop_icon_count_display: contentType: application/json realm_name_in_email_notifications_policy: contentType: application/json automatically_follow_topics_policy: contentType: application/json automatically_unmute_topics_in_muted_streams_policy: contentType: application/json automatically_follow_topics_where_mentioned: contentType: application/json presence_enabled: contentType: application/json enter_sends: contentType: application/json send_private_typing_notifications: contentType: application/json send_stream_typing_notifications: contentType: application/json send_read_receipts: contentType: application/json allow_private_data_export: contentType: application/json email_address_visibility: contentType: application/json web_navigate_to_sent_message: contentType: application/json responses: "200": $ref: "#/components/responses/SuccessIgnoredParameters" /streams/{stream_id}/members: get: operationId: get-subscribers summary: Get channel subscribers tags: ["channels"] description: | Get all users subscribed to a channel. parameters: - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subscribers: type: array items: type: integer description: | A list containing the IDs of all active users who are subscribed to the channel. example: {"result": "success", "msg": "", "subscribers": [11, 26]} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the requested channel does not exist, or where the user does not have permission to access the target channel: /streams: get: operationId: get-streams summary: Get all channels tags: ["channels"] description: | Get all channels that the user [has access to](/help/channel-permissions). x-curl-examples-parameters: oneOf: - type: include parameters: enum: - "" - type: include parameters: enum: - include_public description: | You may pass in one or more of the parameters mentioned below as URL query parameters, like so: parameters: - name: include_public in: query description: | Include all public channels. schema: type: boolean default: true example: false - name: include_web_public in: query description: | Include all web-public channels. schema: type: boolean default: false example: true - name: include_subscribed in: query description: | Include all channels that the user is subscribed to. schema: type: boolean default: true example: false - name: include_all_active in: query description: | Include all active channels. The user must have administrative privileges to use this parameter. schema: type: boolean default: false example: true - name: include_default in: query description: | Include all default channels for the user's realm. schema: type: boolean default: false example: true - name: include_owner_subscribed in: query description: | If the user is a bot, include all channels that the bot's owner is subscribed to. schema: type: boolean default: false example: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} streams: description: | A list of channel objects with details on the requested channels. type: array items: allOf: - $ref: "#/components/schemas/BasicChannelBase" - additionalProperties: false properties: stream_id: {} name: {} description: {} date_created: {} creator_id: nullable: true invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: nullable: true history_public_to_subscribers: {} first_message_id: nullable: true is_announcement_only: {} can_remove_subscribers_group: {} stream_weekly_traffic: type: integer nullable: true description: | The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event. **Changes**: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects. is_default: type: boolean description: | Only present when [`include_default`][include_default] parameter is `true`. Whether the given channel is a [default channel](/help/set-default-channels-for-new-users). [include_default]: /api/get-streams#parameter-include_default required: - stream_id - name - description - date_created - creator_id - invite_only - rendered_description - is_web_public - stream_post_policy - message_retention_days - history_public_to_subscribers - first_message_id - is_announcement_only - can_remove_subscribers_group - stream_weekly_traffic example: { "msg": "", "result": "success", "streams": [ { "can_remove_subscribers_group": 10, "creator_id": null, "date_created": 1691057093, "description": "A private channel", "first_message_id": 18, "history_public_to_subscribers": false, "invite_only": true, "is_announcement_only": false, "is_default": false, "is_web_public": false, "message_retention_days": null, "name": "management", "rendered_description": "A private channel
", "stream_id": 2, "stream_post_policy": 1, "stream_weekly_traffic": null, }, { "can_remove_subscribers_group": 9, "creator_id": 12, "date_created": 1691057093, "description": "A default public channel", "first_message_id": 21, "history_public_to_subscribers": true, "invite_only": false, "is_announcement_only": false, "is_default": true, "is_web_public": false, "message_retention_days": null, "name": "welcome", "rendered_description": "A default public channel
", "stream_id": 1, "stream_post_policy": 1, "stream_weekly_traffic": null, }, ], } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "User not authorized for this query", "result": "error", } description: | An example JSON response for when the user is not authorized to use the `include_all_active` parameter (i.e. because they are not an organization administrator): /streams/{stream_id}: get: operationId: get-stream-by-id summary: Get a channel by ID tags: ["channels"] description: | Fetch details for the channel with the ID `stream_id`. **Changes**: New in Zulip 6.0 (feature level 132). parameters: - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} stream: $ref: "#/components/schemas/BasicChannel" example: { "msg": "", "result": "success", "stream": { "description": "A Scandinavian country", "first_message_id": 1, "history_public_to_subscribers": true, "date_created": 1691057093, "creator_id": null, "invite_only": false, "is_announcement_only": false, "is_web_public": false, "message_retention_days": null, "name": "Denmark", "rendered_description": "A Scandinavian country
", "stream_id": 7, "stream_post_policy": 1, "can_remove_subscribers_group": 2, "stream_weekly_traffic": null, }, } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the channel ID is not valid: delete: operationId: archive-stream summary: Archive a channel tags: ["channels"] description: | [Archive the channel](/help/archive-a-channel) with the ID `stream_id`. x-requires-administrator: true parameters: - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the supplied channel does not exist: patch: operationId: update-stream summary: Update a channel tags: ["channels"] description: | Configure the channel with the ID `stream_id`. This endpoint supports an organization administrator editing any property of a channel, including: - Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description) - Channel [permissions](/help/channel-permissions), including [privacy](/help/change-the-privacy-of-a-channel) and [who can send](/help/channel-posting-policy). Note that an organization administrator's ability to change a [private channel's permissions](/help/channel-permissions#private-channels) depends on them being subscribed to the channel. x-curl-examples-parameters: oneOf: - type: include parameters: enum: - new_name - description - is_private parameters: - $ref: "#/components/parameters/ChannelIdInPath" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: description: description: | The new [description](/help/change-the-channel-description) for the channel, in text/markdown format. Clients should use the `max_stream_description_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum channel description length. **Changes**: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64). type: string example: "Discuss Italian history and travel destinations." new_name: description: | The new name for the channel. Clients should use the `max_stream_name_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum channel name length. **Changes**: Removed unnecessary JSON-encoding of this parameter in Zulip 4.0 (feature level 64). type: string example: Italy is_private: description: | Change whether the channel is a private channel. type: boolean example: true is_announcement_only: deprecated: true description: | Whether the channel is limited to announcements. **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead. type: boolean example: true is_web_public: description: | Change whether the channel is a web-public channel. Note that creating web-public channels requires the `WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings] to be enabled on the Zulip server in question, the organization to have enabled the `enable_spectator_access` realm setting, and the current use to have permission under the organization's `can_create_web_public_channel_group` realm setting. [server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html **Changes**: New in Zulip 5.0 (feature level 98). type: boolean example: true history_public_to_subscribers: description: | Whether the channel's message history should be available to newly subscribed members, or users can only access messages they actually received while subscribed to the channel. Corresponds to the [shared history](/help/channel-permissions) option in documentation. It's an error for this parameter to be false for a public or web-public channel and when is_private is false. **Changes**: Before Zulip 6.0 (feature level 136), `history_public_to_subscribers` was silently ignored unless the request also contained either `is_private` or `is_web_public`. type: boolean example: false is_default_stream: description: | Add or remove the channel as a [default channel][default-channel] for new users joining the organization. [default-channel]: /help/set-default-channels-for-new-users **Changes**: New in Zulip 8.0 (feature level 200). Previously, default channel status could only be changed using the [dedicated API endpoint](/api/add-default-stream). type: boolean example: false stream_post_policy: $ref: "#/components/schemas/ChannelPostPolicy" message_retention_days: $ref: "#/components/schemas/MessageRetentionDays" can_remove_subscribers_group: $ref: "#/components/schemas/CanRemoveSubscribersGroupId" encoding: is_private: contentType: application/json is_announcement_only: contentType: application/json is_web_public: contentType: application/json history_public_to_subscribers: contentType: application/json is_default_stream: contentType: application/json stream_post_policy: contentType: application/json can_remove_subscribers_group: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the supplied channel does not exist: - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid parameters", "result": "error", } description: | An example JSON response for when invalid combination of channel permission parameters are passed: /streams/{stream_id}/email_address: get: operationId: get-stream-email-address summary: Get channel's email address tags: ["channels"] description: | Get email address of a channel. **Changes**: New in Zulip 8.0 (feature level 226). parameters: - $ref: "#/components/parameters/ChannelIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} email: type: string description: | Email address of the channel. example: { "result": "success", "msg": "", "email": "test.af64447e9e39374841063747ade8e6b0.show-sender@testserver", } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/InvalidChannelError" - description: | An example JSON response for when the requested channel does not exist, or where the user does not have permission to access the target channel: /streams/{stream_id}/delete_topic: post: operationId: delete-topic summary: Delete a topic tags: ["channels"] description: | Delete all messages in a topic. Topics are a field on messages (not an independent data structure), so deleting all the messages in the topic deletes the topic from Zulip. Because this endpoint deletes messages in batches, it is possible for the request to time out after only deleting some messages in the topic. When this happens, the `complete` boolean field in the success response will be `false`. Clients should repeat the request when handling such a response. If all messages in the topic were deleted, then the success response will return `"complete": true`. **Changes**: Before Zulip 9.0 (feature level 256), the server never sent [`stream` op: `update`](/api/get-events#stream-update) events with an updated `first_message_id` for a channel when the oldest message that had been sent to it changed. Before Zulip 8.0 (feature level 211), if the server's processing was interrupted by a timeout, but some messages in the topic were deleted, then it would return `"result": "partially_completed"`, along with a `code` field for an error string, in the success response to indicate that there was a timeout and that the client should repeat the request. As of Zulip 6.0 (feature level 154), instead of returning an error response when a request times out after successfully deleting some of the messages in the topic, a success response is returned with `"result": "partially_completed"` to indicate that some messages were deleted. Before Zulip 6.0 (feature level 147), this request did a single atomic operation, which could time out for very large topics. As of this feature level, messages are deleted in batches, starting with the newest messages, so that progress is made even if the request times out and returns an error. x-requires-administrator: true parameters: - $ref: "#/components/parameters/ChannelIdInPath" requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: topic_name: description: | The name of the topic to delete. type: string example: new coffee machine required: - topic_name responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false required: - complete properties: result: {} msg: {} ignored_parameters_unsupported: {} complete: type: boolean description: | Whether all unread messages were marked as read. Will be `false` if the request successfully marked some, but not all, messages as read. example: {"msg": "", "result": "success", "complete": true} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Must be an organization administrator", "code": "UNAUTHORIZED_PRINCIPAL", } description: | Error when the user does not have permission to delete topics in this organization: /typing: post: operationId: set-typing-status summary: Set "typing" status tags: ["users"] description: | Notify other users whether the current user is [typing a message][help-typing]. Clients implementing Zulip's typing notifications protocol should work as follows: - Send a request to this endpoint with `"op": "start"` when a user starts composing a message. - While the user continues to actively type or otherwise interact with the compose UI (e.g. interacting with the compose box emoji picker), send regular `"op": "start"` requests to this endpoint, using `server_typing_started_wait_period_milliseconds` in the [`POST /register`][api-register] response as the time interval between each request. - Send a request to this endpoint with `"op": "stop"` when a user has stopped using the compose UI for the time period indicated by `server_typing_stopped_wait_period_milliseconds` in the [`POST /register`][api-register] response or when a user cancels the compose action (if it had previously sent a "start" notification for that compose action). - Start displaying a visual typing indicator for a given conversation when a [`typing op:start`][start-typing] event is received from the server. - Continue displaying a visual typing indicator for the conversation until a [`typing op:stop`][stop-typing] event is received from the server or the time period indicated by `server_typing_started_expiry_period_milliseconds` in the [`POST /register`][api-register] response has passed without a new `typing "op": "start"` event for the conversation. This protocol is designed to allow the server-side typing notifications implementation to be stateless while being resilient as network failures will not result in a user being incorrectly displayed as perpetually typing. See the subsystems documentation on [typing indicators][typing-protocol-docs] for additional design details on Zulip's typing notifications protocol. **Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215) for channel typing notifications, as no client actually implemented the previous API for those. Support for displaying channel typing notifications was new in Zulip 4.0 (feature level 58). Clients should indicate they support processing channel typing notifications via the `stream_typing_notifications` value in the `client_capabilities` parameter of the [`POST /register`][client-capabilities] endpoint. [help-typing]: /help/typing-notifications [api-register]: /api/register-queue [start-typing]: /api/get-events#typing-start [stop-typing]: /api/get-events#typing-stop [client-capabilities]: /api/register-queue#parameter-client_capabilities [typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - topic requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: type: description: | Type of the message being composed. **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as an additional value for this parameter to indicate a channel message is being composed. In Zulip 8.0 (feature level 215), stopped supporting `"private"` as a valid value for this parameter. In Zulip 7.0 (feature level 174), `"direct"` was added as the preferred way to indicate a direct message is being composed, becoming the default value for this parameter and deprecating the original `"private"`. New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. type: string enum: - direct - stream - channel default: direct example: direct op: description: | Whether the user has started (`"start"`) or stopped (`"stop"`) typing. type: string enum: - start - stop example: start to: description: | User IDs of the recipients of the message being typed. Required for the `"direct"` type. Ignored in the case of `"stream"` or `"channel"` type. Clients should send a JSON-encoded list of user IDs, even if there is only one recipient. **Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter for the `"stream"` type. Previously, in the case of the `"stream"` type, it accepted a single-element list containing the ID of the channel. A new parameter, `stream_id`, is now used for this. Note that the `"channel"` type did not exist at this feature level. Support for typing notifications for channel' messages is new in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. Before Zulip 2.0.0, this parameter accepted only a JSON-encoded list of email addresses. Support for the email address-based format was removed in Zulip 3.0 (feature level 11). type: array items: type: integer minLength: 1 example: [9, 10] stream_id: description: | ID of the channel in which the message is being typed. Required for the `"stream"` or `"channel"` type. Ignored in the case of `"direct"` type. **Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element list containing the ID of the channel was passed in `to` parameter. type: integer example: 7 topic: description: | Topic to which message is being typed. Required for the `"stream"` or `"channel"` type. Ignored in the case of `"direct"` type. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. type: string example: typing notifications required: - op encoding: to: contentType: application/json stream_id: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Missing channel ID", "result": "error", } description: | An example JSON error response when the user composes a channel message and `stream_id` is not specified: /user_groups/create: post: operationId: create-user-group summary: Create a user group tags: ["users"] description: | Create a new [user group](/help/user-groups). requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: description: | The name of the user group. type: string example: marketing description: description: | The description of the user group. type: string example: The marketing team. members: description: | An array containing the user IDs of the initial members for the new user group. type: array items: type: integer example: [1, 2, 3, 4] subgroups: description: | An array containing the IDs of the initial subgroups for the new user group. User can add subgroups to the new group irrespective of other permissions for the new group. **Changes**: New in Zulip 10.0 (feature level 311). type: array items: type: integer example: [11] can_add_members_group: allOf: - description: | A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups - $ref: "#/components/schemas/GroupSettingValue" example: 11 can_join_group: allOf: - description: | A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups - $ref: "#/components/schemas/GroupSettingValue" example: 11 can_leave_group: allOf: - description: | A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups - $ref: "#/components/schemas/GroupSettingValue" example: 15 can_manage_group: allOf: - description: | A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. This setting cannot be set to `"role:internet"` and `"role:everyone"` [system groups][system-groups]. **Changes**: New in Zulip 10.0 (feature level 283). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [manage-user-groups]: /help/manage-user-groups - $ref: "#/components/schemas/GroupSettingValue" example: 11 can_mention_group: allOf: - description: | A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. This setting cannot be set to `"role:internet"` and `"role:owners"` [system groups][system-groups]. Before Zulip 9.0 (feature level 258), this parameter could only be the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this parameter was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group - $ref: "#/components/schemas/GroupSettingValue" example: 11 required: - name - description - members encoding: members: contentType: application/json subgroups: contentType: application/json can_add_members_group: contentType: application/json can_join_group: contentType: application/json can_leave_group: contentType: application/json can_manage_group: contentType: application/json can_mention_group: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "code": "BAD_REQUEST", "msg": "Invalid user ID: 500", } description: | An example JSON error response for when the one of the users does not exist: /user_groups/{user_group_id}/members: post: operationId: update-user-group-members summary: Update user group members tags: ["users"] description: | Update the members of a [user group](/help/user-groups). The user IDs must correspond to non-deactivated users. **Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of deactivated users were visible to the API and could be edited via this endpoint. x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - delete parameters: - $ref: "#/components/parameters/UserGroupId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: delete: description: | The list of user IDs to be removed from the user group. type: array items: type: integer example: [10] add: description: | The list of user IDs to be added to the user group. type: array items: type: integer example: [12, 13] delete_subgroups: description: | The list of user group IDs to be removed from the user group. **Changes**: New in Zulip 10.0 (feature level 311). type: array items: type: integer example: [9] add_subgroups: description: | The list of user group IDs to be added to the user group. **Changes**: New in Zulip 10.0 (feature level 311). type: array items: type: integer example: [9] encoding: delete: contentType: application/json add: contentType: application/json delete_subgroups: contentType: application/json add_subgroups: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" get: operationId: get-user-group-members summary: Get user group members tags: ["users"] description: | Get the members of a [user group](/help/user-groups). **Changes**: New in Zulip 6.0 (feature level 127). parameters: - $ref: "#/components/parameters/UserGroupId" - $ref: "#/components/parameters/DirectMemberOnly" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} members: type: array items: type: integer description: | A list containing the user IDs of members of the user group. example: {"msg": "", "result": "success", "members": [10, 12]} /user_groups/{user_group_id}: patch: operationId: update-user-group summary: Update a user group tags: ["users"] description: | Update the name or description of a [user group](/help/user-groups). parameters: - $ref: "#/components/parameters/UserGroupId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: name: description: | The new name of the group. **Changes**: Before Zulip 7.0 (feature level 165), this was a required field. type: string example: marketing team description: description: | The new description of the group. **Changes**: Before Zulip 7.0 (feature level 165), this was a required field. type: string example: The marketing team. can_add_members_group: description: | The set of users who have permission to add members to this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups type: object additionalProperties: false properties: new: allOf: - description: | The new [group-setting value](/api/group-setting-values) for the set of users who would have the permission to add members to the group. - $ref: "#/components/schemas/GroupSettingValue" old: allOf: - description: | The expected current [group-setting value](/api/group-setting-values) for the set of users who have the permission to add members to the group. - $ref: "#/components/schemas/GroupSettingValue" required: - new example: { "new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11, } can_join_group: description: | The set of users who have permission to join this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 301). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups type: object additionalProperties: false properties: new: allOf: - description: | The new [group-setting value](/api/group-setting-values) for who would have the permission to join the group. - $ref: "#/components/schemas/GroupSettingValue" old: allOf: - description: | The expected current [group-setting value](/api/group-setting-values) for who has the permission to join the group. - $ref: "#/components/schemas/GroupSettingValue" required: - new example: { "new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11, } can_leave_group: description: | The set of users who have permission to leave this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 308). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups type: object additionalProperties: false properties: new: allOf: - description: | The new [group-setting value](/api/group-setting-values) for who would have the permission to leave the group. - $ref: "#/components/schemas/GroupSettingValue" old: allOf: - description: | The expected current [group-setting value](/api/group-setting-values) for who has the permission to leave the group. - $ref: "#/components/schemas/GroupSettingValue" required: - new example: { "new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15, } can_manage_group: description: | The set of users who have permission to [manage this user group][manage-user-groups] expressed as an [update to a group-setting value][update-group-setting]. This setting cannot be set to `"role:internet"` and `"role:everyone"` [system groups][system-groups]. **Changes**: New in Zulip 10.0 (feature level 283). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups [manage-user-groups]: /help/manage-user-groups type: object additionalProperties: false properties: new: allOf: - description: | The new [group-setting value](/api/group-setting-values) for who would have the permission to manage the group. - $ref: "#/components/schemas/GroupSettingValue" old: allOf: - description: | The expected current [group-setting value](/api/group-setting-values) for who has the permission to manage the group. - $ref: "#/components/schemas/GroupSettingValue" required: - new example: { "new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11, } can_mention_group: description: | The set of users who have permission to [mention this group][mentions], expressed as an [update to a group-setting value][update-group-setting]. This setting cannot be set to `"role:internet"` and `"role:owners"` [system groups][system-groups]. **Changes**: In Zulip 9.0 (feature level 260), this parameter was updated to only accept an object with the `old` and `new` fields described below. Prior to this feature level, this parameter could be either of the two forms of a [group-setting value][setting-values]. Before Zulip 9.0 (feature level 258), this parameter could only be the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this parameter was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. [mentions]: /help/mention-a-user-or-group [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups [setting-values]: /api/group-setting-values type: object additionalProperties: false properties: new: allOf: - description: | The new [group-setting value](/api/group-setting-values) for who would have the permission to mention the group. - $ref: "#/components/schemas/GroupSettingValue" old: allOf: - description: | The expected current [group-setting value](/api/group-setting-values) for who has the permission to mention the group. - $ref: "#/components/schemas/GroupSettingValue" required: - new example: { "new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11, } encoding: can_add_members_group: contentType: application/json can_join_group: contentType: application/json can_leave_group: contentType: application/json can_manage_group: contentType: application/json can_mention_group: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid user group", "result": "error", } description: | An example JSON response when the user group ID is invalid: /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. requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: include_deactivated_groups: description: | Whether to include deactivated user groups in the response. **Changes**: In Zulip 10.0 (feature level 294), renamed `allow_deactivated` to `include_deactivated_groups`. New in Zulip 10.0 (feature level 290). Previously, deactivated user groups did not exist and thus would never be included in the response. type: boolean example: true default: false encoding: allow_deactivated: contentType: application/json 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. date_created: type: integer nullable: true description: | The UNIX timestamp for when the user group was created, in UTC seconds. A `null` value means the user group has no recorded date, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html creator_id: type: integer nullable: true description: | The ID of the user who created this user group. A `null` value means the user group has no recorded creator, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html members: type: array description: | The integer user IDs of the user group's members, which are guaranteed to be non-deactivated users in the organization. **Changes**: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated. 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_add_members_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values can_join_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values can_leave_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values can_manage_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups can_mention_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group deactivated: type: boolean description: | Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). description: | A list of `user_group` objects. example: { "msg": "", "result": "success", "user_groups": [ { "description": "Owners of this organization", "id": 1, "creator_id": null, "date_created": null, "name": "role:owners", "members": [1], "direct_subgroup_ids": [], "is_system_group": true, "can_add_members_group": 16, "can_join_group": 16, "can_leave_group": 15, "can_manage_group": 16, "can_mention_group": 11, }, { "description": "Administrators of this organization, including owners", "id": 2, "creator_id": null, "date_created": null, "name": "role:administrators", "members": [2], "direct_subgroup_ids": [1], "is_system_group": true, "can_add_members_group": 17, "can_join_group": 17, "can_leave_group": 15, "can_manage_group": 17, "can_mention_group": 12, }, { "description": "Characters of Hamlet", "id": 3, "creator_id": null, "date_created": 1717484476, "name": "hamletcharacters", "members": [3, 4], "direct_subgroup_ids": [], "is_system_group": false, "can_add_members_group": 20, "can_join_group": 20, "can_leave_group": 15, "can_manage_group": 20, "can_mention_group": 13, }, ], } /user_groups/{user_group_id}/subgroups: post: operationId: update-user-group-subgroups summary: Update subgroups of a user group tags: ["users"] description: | Update the subgroups of a [user group](/help/user-groups). **Changes**: New in Zulip 6.0 (feature level 127). x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - delete parameters: - $ref: "#/components/parameters/UserGroupId" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: delete: description: | The list of user group IDs to be removed from the user group. type: array items: type: integer example: [10] add: description: | The list of user group IDs to be added to the user group. type: array items: type: integer example: [10] encoding: delete: contentType: application/json add: contentType: application/json responses: "200": $ref: "#/components/responses/SimpleSuccess" get: operationId: get-user-group-subgroups summary: Get subgroups of a user group tags: ["users"] description: | Get the subgroups of a [user group](/help/user-groups). **Changes**: New in Zulip 6.0 (feature level 127). parameters: - $ref: "#/components/parameters/UserGroupId" - name: direct_subgroup_only in: query description: | Whether to consider only direct subgroups of the user group or subgroups of subgroups also. schema: type: boolean default: false example: true required: false responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subgroups: type: array items: type: integer description: | A list containing the IDs of subgroups of the user group. example: {"msg": "", "result": "success", "subgroups": [2, 3]} /user_groups/{user_group_id}/members/{user_id}: get: operationId: get-is-user-group-member summary: Get user group membership status tags: ["users"] description: | Check whether a user is member of user group. **Changes**: Prior to Zulip 10.0 (feature level 303), this would return true when passed a deactivated user who was a member of the user group before being deactivated. 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, } /user_groups/{user_group_id}/deactivate: post: operationId: deactivate-user-group summary: Deactivate a user group tags: ["users"] description: | Deactivate a user group. Deactivated user groups cannot be used for mentions, permissions, or any other purpose, but can be reactivated or renamed. Deactivating user groups is preferable to deleting them from the database, since the deactivation model allows audit logs of changes to sensitive group-valued permissions to be maintained. **Changes**: New in Zulip 10.0 (feature level 290). parameters: - $ref: "#/components/parameters/UserGroupId" 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": "Invalid user group", "result": "error", } description: | An example JSON response when the user group ID is invalid. - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "CANNOT_DEACTIVATE_GROUP_IN_USE", "msg": "Cannot deactivate user group in use.", "objections": [ { "type": "realm", "settings": ["can_create_public_channel_group"], }, ], "result": "error", } description: | An example JSON response when the user group being deactivated is used for a setting or as a subgroup. **Changes**: New in Zulip 10.0 (feature level 298). Previously, this error returned the `"BAD_REQUEST"` code. /real-time: # This entry is a hack; it exists to give us a place to put the text # documenting the parameters for call_on_each_event and friends. post: tags: ["real_time_events"] description: | (Ignored) requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: event_types: $ref: "#/components/schemas/Event_types" narrow: $ref: "#/components/schemas/Narrow" all_public_streams: $ref: "#/components/schemas/AllPublicChannels" encoding: event_types: contentType: application/json narrow: contentType: application/json all_public_streams: contentType: application/json security: - basicAuth: [] responses: # Makeshift response for this hack entry. "200": description: Success /rest-error-handling: post: operationId: rest-error-handling summary: Error handling tags: ["real_time_events"] description: | Common error to many endpoints responses: "400": description: | Bad request. content: application/json: schema: oneOf: - $ref: "#/components/schemas/InvalidApiKeyError" - $ref: "#/components/schemas/MissingArgumentError" - $ref: "#/components/schemas/IncompatibleParametersError" - $ref: "#/components/schemas/UserNotAuthorizedError" "401": description: | Unauthorized. content: application/json: schema: oneOf: - $ref: "#/components/schemas/UserDeactivatedError" - $ref: "#/components/schemas/RealmDeactivatedError" "429": description: | Rate limit exceeded. content: application/json: schema: oneOf: - $ref: "#/components/schemas/RateLimitedError" /zulip-outgoing-webhook: post: operationId: zulip-outgoing-webhooks summary: Outgoing webhooks tags: ["webhooks"] description: | Outgoing webhooks allow you to build or set up Zulip integrations which are notified when certain types of messages are sent in Zulip. responses: "200": description: | Success content: application/json: schema: type: object additionalProperties: false description: | This is an example of the JSON payload that the Zulip server will `POST` to your server: properties: bot_email: type: string description: | Email of the bot user. bot_full_name: type: string description: | The full name of the bot user. data: type: string description: | The message content, in raw Markdown format (not rendered to HTML). trigger: type: string description: | What aspect of the message triggered the outgoing webhook notification. Possible values include `direct_message` and `mention`. **Changes**: In Zulip 8.0 (feature level 201), renamed the trigger `private_message` to `direct_message`. token: type: string description: | A string of alphanumeric characters that can be used to authenticate the webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot in the `zuliprc` file downloaded when creating the bot. message: description: | A dictionary containing details on the message that triggered the outgoing webhook, in the format used by [`GET /messages`](/api/get-messages). allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: nullable: true client: {} content: {} content_type: {} display_recipient: {} edit_history: {} id: {} is_me_message: {} last_edit_timestamp: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} submessages: {} timestamp: {} topic_links: {} type: {} rendered_content: type: string description: | The content/body of the message rendered in HTML. example: { "data": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!", "trigger": "mention", "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0", "message": { "subject": "Verona2", "sender_email": "iago@zulip.com", "timestamp": 1527876931, "client": "website", "submessages": [], "recipient_id": 20, "topic_links": [], "sender_full_name": "Iago", "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1", "rendered_content": "@Outgoing webhook test Zulip is the world\u2019s most productive group chat!
", "sender_id": 5, "stream_id": 5, "content": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!", "display_recipient": "Verona", "type": "stream", "id": 112, "is_me_message": false, "reactions": [], "sender_realm_str": "zulip", }, "bot_email": "outgoing-bot@localhost", "bot_full_name": "Outgoing webhook test", } /calls/bigbluebutton/create: get: tags: ["channels"] operationId: create-big-blue-button-video-call summary: Create BigBlueButton video call description: | Create a video call URL for a BigBlueButton video call. Requires [BigBlueButton](/integrations/doc/big-blue-button) to be configured on the Zulip server. parameters: - in: query name: meeting_name schema: type: string required: true description: | Meeting name for the BigBlueButton video call. example: "test_channel meeting" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} url: description: | The URL for the BigBlueButton video call. type: string example: "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22" example: { "msg": "", "result": "success", "url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22", } components: ####################### # Security definitions ####################### securitySchemes: BasicAuth: type: http scheme: basic description: | Basic authentication, with the user's email as the username, and the API key as the password. The API key can be fetched using the `/fetch_api_key` or `/dev_fetch_api_key` endpoints. schemas: IgnoredParametersUnsupported: type: array items: type: string description: | An array of any parameters sent in the request that are not supported by the endpoint. See [error handling](/api/rest-error-handling#ignored-parameters) documentation for details on this and its change history. EventIdSchema: type: integer description: | The ID of the event. Events appear in increasing order but may not be consecutive. EventTypeSchema: type: string description: | The event's type, relevant both for client-side dispatch and server-side filtering by event type in [POST /register](/api/register-queue). Anchor: type: string Attachments: type: object description: | Dictionary containing details of a file uploaded by a user. additionalProperties: false properties: id: type: integer description: | The unique ID for the attachment. name: type: string description: | Name of the uploaded file. path_id: type: string description: | A representation of the path of the file within the repository of user-uploaded files. If the `path_id` of a file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be: `{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`. size: type: integer description: | Size of the file in bytes. create_time: type: integer description: | Time when the attachment was uploaded as a UNIX timestamp multiplied by 1000 (matching the format of getTime() in JavaScript). **Changes**: Changed in Zulip 3.0 (feature level 22). This field was previously a floating point number. messages: type: array description: | Contains basic details on any Zulip messages that have been sent referencing this [uploaded file](/api/upload-file). This includes messages sent by any user in the Zulip organization who sent a message containing a link to the uploaded file. items: type: object additionalProperties: false properties: date_sent: type: integer description: | Time when the message was sent as a UNIX timestamp multiplied by 1000 (matching the format of getTime() in JavaScript). **Changes**: Changed in Zulip 3.0 (feature level 22). This field was previously strangely called `name` and was a floating point number. id: type: integer description: | The unique message ID. Messages should always be displayed sorted by ID. BasicChannel: allOf: - $ref: "#/components/schemas/BasicChannelBase" - additionalProperties: false properties: stream_id: {} name: {} description: {} date_created: {} creator_id: nullable: true invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: nullable: true history_public_to_subscribers: {} first_message_id: nullable: true is_announcement_only: {} can_remove_subscribers_group: {} stream_weekly_traffic: type: integer nullable: true description: | The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, no information is provided on the average traffic. This can be because the channel was recently created and there is insufficient data to make an estimate, or because the server wishes to omit this information for this client, this realm, or this endpoint or type of event. **Changes**: New in Zulip 8.0 (feature level 199). Previously, this statistic was available only in subscription objects. required: - stream_id - name - description - date_created - creator_id - invite_only - rendered_description - is_web_public - stream_post_policy - message_retention_days - history_public_to_subscribers - first_message_id - is_announcement_only - can_remove_subscribers_group - stream_weekly_traffic DefaultChannel: allOf: - $ref: "#/components/schemas/BasicChannelBase" - additionalProperties: false properties: stream_id: {} name: {} description: {} date_created: {} creator_id: nullable: true invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: nullable: true history_public_to_subscribers: {} first_message_id: nullable: true is_announcement_only: {} can_remove_subscribers_group: {} required: - stream_id - name - description - date_created - creator_id - invite_only - rendered_description - is_web_public - stream_post_policy - message_retention_days - history_public_to_subscribers - first_message_id - is_announcement_only - can_remove_subscribers_group BasicChannelBase: type: object description: | Object containing basic details about the channel. properties: stream_id: type: integer description: | The unique ID of the channel. name: type: string description: | The name of the channel. description: type: string description: | The short description of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description. date_created: type: integer description: | The UNIX timestamp for when the channel was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). creator_id: type: integer nullable: true description: | The ID of the user who created this channel. A `null` value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 9.0 (feature level 254). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html invite_only: type: boolean description: | Specifies whether the channel is private or not. Only people who have been invited can access a private channel. rendered_description: type: string description: | The short description of the channel rendered as HTML, intended to be used when displaying the channel description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. is_web_public: type: boolean description: | Whether the channel has been configured to allow unauthenticated access to its message history from the web. **Changes**: New in Zulip 2.1.0. stream_post_policy: type: integer description: | [Policy][permission-level] for which users can post messages to the channel. - 1 = Any user can post. - 2 = Only administrators can post. - 3 = Only [full members][calc-full-member] can post. - 4 = Only moderators can post. **Changes**: New in Zulip 3.0 (feature level 1), replacing the previous `is_announcement_only` boolean. [permission-level]: /api/roles-and-permissions#permission-levels [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member message_retention_days: type: integer nullable: true description: | Number of days that messages sent to this channel will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). There are two special values: - `null`, the default, means the channel will inherit the organization level setting. - `-1` encodes retaining messages in this channel forever. **Changes**: New in Zulip 3.0 (feature level 17). history_public_to_subscribers: type: boolean description: | Whether the history of the channel is public to its subscribers. Currently always true for public channels (i.e. `"invite_only": false` implies `"history_public_to_subscribers": true`), but clients should not make that assumption, as we may change that behavior in the future. first_message_id: type: integer nullable: true description: | The ID of the first message in the channel. Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed. Is `null` for channels with no message history. **Changes**: New in Zulip 2.1.0. is_announcement_only: type: boolean deprecated: true description: | Whether the given channel is announcement only or not. **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead. can_remove_subscribers_group: type: integer description: | ID of the user group whose members are allowed to unsubscribe others from the channel. **Changes**: Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group` setting was named `can_remove_subscribers_group_id`. New in Zulip 6.0 (feature level 142). BasicBot: allOf: - $ref: "#/components/schemas/BasicBotBase" - additionalProperties: false properties: user_id: {} full_name: {} api_key: {} default_sending_stream: nullable: true default_events_register_stream: nullable: true default_all_public_streams: {} avatar_url: {} owner_id: nullable: true services: {} is_active: type: boolean description: | A boolean describing whether the user account has been deactivated. **Changes**: New in Zulip 8.0 (feature level 222). Previously we sent `realm_user` event with `op` field set to `remove` when deactivating a bot and `realm_user` event with `op` field set to `add` when reactivating a bot. BasicBotBase: type: object properties: user_id: type: integer description: | The user ID of the bot. full_name: type: string description: | The full name of the bot. api_key: type: string description: | The API key of the bot which it uses to make API requests. default_sending_stream: type: string nullable: true description: | The default sending channel of the bot. If `null`, the bot doesn't have a default sending channel. default_events_register_stream: type: string nullable: true description: | The default channel for which the bot receives events/register data. If `null`, the bot doesn't have such a default channel. default_all_public_streams: type: boolean description: | Whether the bot can send messages to all channels by default. avatar_url: type: string description: | The URL of the bot's avatar. owner_id: type: integer nullable: true description: | The user ID of the bot's owner. If `null`, the bot has no owner. services: type: array description: | An array containing extra configuration fields only relevant for outgoing webhook bots and embedded bots. This is always a single-element array. We consider this part of the Zulip API to be unstable; it is used only for UI elements for administering bots and is likely to change. items: description: | Object with extra configuration details for the bot. The fields in the object depend on the type of bot. oneOf: - type: object additionalProperties: false description: | When the bot is an outgoing webhook. properties: base_url: type: string description: | The URL the outgoing webhook is configured to post to. token: type: string description: | A unique token that the third-party service can use to confirm that the request is indeed coming from Zulip. interface: type: integer description: | An integer indicating what format requests are posted in: - 1 = Zulip's native outgoing webhook format. - 2 = Emulate the Slack outgoing webhook format. - type: object additionalProperties: false description: | When the bot is an embedded bot. properties: service_name: type: string description: | The name of the bot. config_data: $ref: "#/components/schemas/BotConfiguration" Bot: allOf: - $ref: "#/components/schemas/BasicBotBase" - description: | Object containing details of a bot. additionalProperties: false properties: user_id: {} full_name: {} api_key: {} default_sending_stream: nullable: true default_events_register_stream: nullable: true default_all_public_streams: {} avatar_url: {} owner_id: nullable: true services: {} email: type: string description: | The email of the bot. bot_type: type: integer nullable: true description: | An integer describing the type of bot: - `1` for a `Generic` bot. - `2` for an `Incoming webhook` bot. - `3` for an `Outgoing webhook` bot. - `4` for an `Embedded` bot. is_active: type: boolean description: | A boolean describing whether the user account has been deactivated. BotConfiguration: type: object description: | A dictionary of string key/value pairs, which describe the configuration for the bot. These are usually details like API keys, and are unique to the integration/bot. Can be an empty dictionary. additionalProperties: description: | `{config_key}`: Description/value of the configuration data key. type: string CustomProfileField: type: object additionalProperties: false description: | Dictionary containing the details of a custom profile field configured for this organization. properties: id: type: integer description: | The ID of the custom profile field. This will be referenced in the custom profile fields section of user objects. type: type: integer description: | An integer indicating the type of the custom profile field, which determines how it is configured and displayed to users. See the [Custom profile fields](/help/custom-profile-fields#profile-field-types) article for details on what each type means. - **1**: Short text - **2**: Long text - **3**: List of options - **4**: Date picker - **5**: Link - **6**: Person picker - **7**: External account - **8**: Pronouns **Changes**: Field type `8` added in Zulip 6.0 (feature level 151). order: type: integer description: | Custom profile fields are displayed in both settings UI and UI showing users' profiles in increasing `order`. name: type: string description: | The name of the custom profile field. hint: type: string description: | The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields. field_data: type: string description: | Field types 3 (List of options) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (List of options), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option. The interface for field type 7 is not yet stabilized. display_in_profile_summary: type: boolean description: | Whether the custom profile field, display or not on the user card. Currently it's value not allowed to be `true` of `Long text` and `Person picker` [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: New in Zulip 6.0 (feature level 146). default: false required: type: boolean description: | Whether an organization administrator has configured this profile field as required. Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field. **Changes**: New in Zulip 9.0 (feature level 244). editable_by_user: type: boolean description: | Whether regular users can edit this profile field on their own account. Note that organization administrators can edit custom profile fields for any user regardless of this setting. **Changes**: New in Zulip 10.0 (feature level 296). default: true required: - id - type - order - name - hint - required - editable_by_user OnboardingStep: type: object additionalProperties: false description: | Dictionary containing details of a single onboarding step. properties: type: type: string description: | The type of the onboarding step. Valid value is `"one_time_notice"`. **Changes**: Removed type `"hotspot"` in Zulip 9.0 (feature level 259). New in Zulip 8.0 (feature level 233). name: type: string description: | The name of the onboarding step. RealmAuthenticationMethod: type: object properties: enabled: type: boolean description: | Boolean describing whether the authentication method (i.e. its key) is enabled in this organization. available: type: boolean description: | Boolean describing whether the authentication method is available for use. If false, the organization is not eligible to enable the authentication method. unavailable_reason: type: string description: | Reason why the authentication method is unavailable. This field is optional and is only present when 'available' is false. additionalProperties: false description: | Dictionary describing the properties of an authentication method for the organization - its enabled status and availability for use by the organization. RealmEmoji: type: object additionalProperties: false description: | `{emoji_id}`: Object containing details about the emoji with the specified ID. It has the following properties: properties: id: type: string description: | The ID for this emoji, same as the object's key. name: type: string description: | The user-friendly name for this emoji. Users in the organization can use this emoji by writing this name between colons (`:name :`). source_url: type: string description: | The path relative to the organization's URL where the emoji's image can be found. still_url: type: string nullable: true description: | Only non-null when the emoji's image is animated. The path relative to the organization's URL where a still (not animated) version of the emoji can be found. (This is currently always the first frame of the animation). This is useful for clients to display the emoji in contexts where continuously animating it would be a bad user experience (E.g. because it would be distracting). **Changes**: New in Zulip 5.0 (added as optional field in feature level 97 and then made mandatory, but nullable, in feature level 113). deactivated: type: boolean description: | Whether the emoji has been deactivated or not. author_id: type: integer nullable: true description: | The user ID of the user who uploaded the custom emoji. Will be `null` if the uploader is unknown. **Changes**: New in Zulip 3.0 (feature level 7). Previously was accessible via an `author` object with an `id` field. RealmDomain: type: object additionalProperties: false description: | Object containing details of the newly added domain. properties: domain: type: string description: | The new allowed domain. allow_subdomains: type: boolean description: | Whether subdomains are allowed for this domain. RealmPlayground: type: object additionalProperties: false description: | Object containing details about a realm playground. properties: id: type: integer description: | The unique ID for the realm playground. name: type: string description: | The user-visible display name of the playground. Clients should display this in UI for picking which playground to open a code block in, to differentiate between multiple configured playground options for a given pygments language. **Changes**: New in Zulip 4.0 (feature level 49). pygments_language: type: string description: | The name of the Pygments language lexer for that programming language. url_template: type: string description: | The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template for the playground. The template contains exactly one variable named `code`, which determines how the extracted code should be substituted in the playground URL. **Changes**: New in Zulip 8.0 (feature level 196). This replaced the `url_prefix` parameter, which was used to construct URLs by just concatenating url_prefix and code. RealmExport: type: object additionalProperties: false description: | Object containing details about a [data export](/help/export-your-organization). properties: id: type: integer description: | The ID of the data export. acting_user_id: type: integer description: | The ID of the user who created the data export. export_time: type: number description: | The UNIX timestamp of when the data export was started. deleted_timestamp: type: number nullable: true description: | The UNIX timestamp of when the data export was deleted. Will be `null` if the data export has not been deleted. failed_timestamp: type: number nullable: true description: | The UNIX timestamp of when the data export failed. Will be `null` if the data export succeeded, or if it's still being generated. export_url: type: string nullable: true description: | The URL to download the generated data export. Will be `null` if the data export failed, or if it's still being generated. pending: type: boolean description: | Whether the data export is pending, which indicates it is still being generated, or if it succeeded, failed or was deleted before being generated. Depending on the size of the organization, it can take anywhere from seconds to an hour to generate the data export. export_type: type: integer description: | Whether the data export is a public or a standard data export. - 1 = Public data export. - 2 = Standard data export. **Changes**: New in Zulip 10.0 (feature level 304). Previously, the export type was not included in these objects because only public data exports could be created or listed via the API or UI. UserGroup: type: object additionalProperties: false description: | Object containing the user group's attributes. properties: name: type: string description: | The name of the user group. date_created: type: integer nullable: true description: | The UNIX timestamp for when the user group was created, in UTC seconds. A `null` value means the user group has no recorded date, which is often because the user group is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html creator_id: type: integer nullable: true description: | The ID of the user who created this user group. A `null` value means the user group has no recorded creator, which is often because the user group is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html 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. **Changes**: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated. 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_add_members_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values can_join_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values can_leave_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values can_manage_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups can_mention_group: allOf: - $ref: "#/components/schemas/GroupSettingValue" - description: | A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group deactivated: type: boolean description: | Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). GroupSettingValue: oneOf: - type: integer description: | The ID of the [user group](/help/user-groups) with this permission. - type: object additionalProperties: false properties: direct_members: description: | The list of IDs of individual users in the collection of users with this permission. **Changes**: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated. type: array items: type: integer direct_subgroups: description: | The list of IDs of the groups in the collection of users with this permission. type: array items: type: integer description: | An object with these fields: Invite: type: object description: | A dictionary containing details about an [invitation](/help/invite-new-users). additionalProperties: false properties: id: type: integer description: | The ID of the invitation. Note that email invitations and reusable invitation links are stored in different database tables on the server, so each ID is guaranteed to be unique in combination with the boolean value of `is_multiuse`, e.g. there can only be one invitation with `id: 1` and `is_multiuse: true`. invited_by_user_id: type: integer description: | The [user ID](/api/get-user) of the user who created the invitation. **Changes**: New in Zulip 3.0 (feature level 22), replacing the `ref` field which contained the Zulip display email address of the user who created the invitation. invited: type: integer description: | The UNIX timestamp for when the invitation was created, in UTC seconds. expiry_date: type: integer nullable: true description: | The UNIX timestamp for when the invitation will expire, in UTC seconds. If `null`, the invitation never expires. invited_as: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: | The [organization-level role](/api/roles-and-permissions) of the user that is created when the invitation is accepted. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest email: type: string description: | The email address the invitation was sent to. This will not be present when `is_multiuse` is `true` (i.e. the invitation is a reusable invitation link). notify_referrer_on_join: type: boolean description: | A boolean indicating whether the referrer has opted to receive a direct message from [notification bot](/help/configure-automated-notices) when a user account is created using this invitation. **Changes**: New in Zulip 9.0 (feature level 267). Previously, referrers always received such direct messages. link_url: type: string description: | The URL of the reusable invitation link. This will not be present when `is_multiuse` is `false` (i.e. the invitation is an email invitation). is_multiuse: type: boolean description: | A boolean specifying whether the [invitation](/help/invite-new-users) is a reusable invitation link or an email invitation. InviteExpirationParameter: description: | The number of minutes before the invitation will expire. If `null`, the invitation will never expire. If unspecified, the server will use a default value (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which defaults to 14400, i.e. 10 days) for when the invitation will expire. **Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an `invite_expires_in_days` parameter, which specified the duration in days instead of minutes. type: integer nullable: true example: 14400 InviteRoleParameter: description: | The [organization-level role](/api/roles-and-permissions) of the user that is created when the invitation is accepted. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest Users can only create invitation links for [roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels) as their own. For example, a moderator cannot invite someone to be an owner or administrator, but they can invite them to be a moderator or member. **Changes**: In Zulip 4.0 (feature level 61), added support for inviting users as moderators. type: integer enum: - 100 - 200 - 300 - 400 - 600 default: 400 example: 600 Subscriptions: type: object additionalProperties: false properties: stream_id: type: integer description: | The unique ID of a channel. name: type: string description: | The name of a channel. description: type: string description: | The [description](/help/change-the-channel-description) of the channel in text/markdown format, intended to be used to prepopulate UI for editing a channel's description. See also `rendered_description`. rendered_description: type: string description: | The [description](/help/change-the-channel-description) of the channel rendered as HTML, intended to be used when displaying the channel description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. See also `description`. date_created: type: integer description: | The UNIX timestamp for when the channel was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). creator_id: type: integer nullable: true description: | The ID of the user who created this channel. A `null` value means the channel has no recorded creator, which is often because the channel is very old, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 9.0 (feature level 254). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html invite_only: type: boolean description: | Specifies whether the channel is private or not. Only people who have been invited can access a private channel. # TODO: This subscribers item should probably be declared optional more # explicitly in the OpenAPI format? subscribers: type: array items: type: integer description: | A list of user IDs of users who are also subscribed to a given channel. Included only if `include_subscribers` is `true`. desktop_notifications: type: boolean nullable: true description: | A boolean specifying whether desktop notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_desktop_notifications`, for this channel. email_notifications: type: boolean nullable: true description: | A boolean specifying whether email notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_email_notifications`, for this channel. wildcard_mentions_notify: type: boolean nullable: true description: | A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this channel. A `null` value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this channel. push_notifications: type: boolean nullable: true description: | A boolean specifying whether push notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_push_notifications`, for this channel. audible_notifications: type: boolean nullable: true description: | A boolean specifying whether audible notifications are enabled for the given channel. A `null` value means the value of this setting should be inherited from the user-level default setting, `enable_stream_audible_notifications`, for this channel. pin_to_top: type: boolean description: | A boolean specifying whether the given channel has been pinned to the top. is_muted: type: boolean description: | Whether the user has muted the channel. Muted channels do not count towards your total unread count and do not show up in the `Combined feed` view (previously known as `All messages`). **Changes**: Prior to Zulip 2.1.0, this feature was represented by the more confusingly named `in_home_view` (with the opposite value, `in_home_view=!is_muted`). in_home_view: type: boolean deprecated: true description: | Legacy property for if the given channel is muted, with inverted meaning. **Changes**: Deprecated in Zulip 2.1.0. Clients should use `is_muted` where available. is_announcement_only: type: boolean deprecated: true description: | Whether only organization administrators can post to the channel. **Changes**: Deprecated in Zulip 3.0 (feature level 1). Clients should use `stream_post_policy` instead. is_web_public: type: boolean description: | Whether the channel has been configured to allow unauthenticated access to its message history from the web. color: type: string description: | The user's personal color for the channel. stream_post_policy: type: integer description: | [Policy][permission-level] for which users can post messages to the channel. - 1 = Any user can post. - 2 = Only administrators can post. - 3 = Only [full members][calc-full-member] can post. - 4 = Only moderators can post. **Changes**: New in Zulip 3.0 (feature level 1), replacing the previous `is_announcement_only` boolean. [permission-level]: /api/roles-and-permissions#permission-levels [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member message_retention_days: type: integer nullable: true description: | Number of days that messages sent to this channel will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). There are two special values: - `null`, the default, means the channel will inherit the organization level setting. - `-1` encodes retaining messages in this channel forever. **Changes**: New in Zulip 3.0 (feature level 17). history_public_to_subscribers: type: boolean description: | Whether the history of the channel is public to its subscribers. Currently always true for public channels (i.e. `"invite_only": false` implies `"history_public_to_subscribers": true`), but clients should not make that assumption, as we may change that behavior in the future. first_message_id: type: integer nullable: true description: | The ID of the first message in the channel. Intended to help clients determine whether they need to display UI like the "show all topics" widget that would suggest the channel has older history that can be accessed. Is `null` for channels with no message history. stream_weekly_traffic: type: integer nullable: true description: | The average number of messages sent to the channel per week, as estimated based on recent weeks, rounded to the nearest integer. If `null`, the channel was recently created and there is insufficient data to estimate the average traffic. can_remove_subscribers_group: type: integer description: | ID of the user group whose members are allowed to unsubscribe others from the channel. **Changes**: Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group` setting was named `can_remove_subscribers_group_id`. New in Zulip 6.0 (feature level 142). DefaultChannelGroup: type: object description: | Dictionary containing details of a default channel group. additionalProperties: false properties: name: type: string description: | Name of the default channel group. description: type: string description: | Description of the default channel group. id: type: integer description: | The ID of the default channel group. streams: type: array description: | Array containing details about the channels in the default channel group. items: $ref: "#/components/schemas/DefaultChannel" EmailAddressVisibility: type: integer description: | The [policy][permission-level] for [which other users][help-email-visibility] in this organization can see the user's real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility EmojiReaction: allOf: - $ref: "#/components/schemas/EmojiBase" - additionalProperties: false properties: emoji_code: {} emoji_name: {} reaction_type: {} user_id: type: integer description: | The ID of the user who added the reaction. **Changes**: New in Zulip 3.0 (feature level 2). The `user` object is deprecated and will be removed in the future. user: type: object additionalProperties: false deprecated: true description: | Dictionary with data on the user who added the reaction, including the user ID as the `id` field. Note that reactions data received from the [events API](/api/get-events) has a slightly different `user` dictionary format, with the user ID field called `user_id` instead. **Changes**: Deprecated and to be removed in a future release once core clients have migrated to use the adjacent `user_id` field, which was introduced in Zulip 3.0 (feature level 2). Clients supporting older Zulip server versions should use the user ID mentioned in the description above as they would the `user_id` field. properties: id: type: integer description: | ID of the user. email: type: string description: | Zulip API email of the user. full_name: type: string description: | Full name of the user. is_mirror_dummy: type: boolean description: | Whether the user is a mirror dummy. EmojiBase: type: object properties: emoji_name: type: string description: | Name of the emoji. emoji_code: type: string description: | A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. reaction_type: type: string enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: | A string indicating the type of emoji. Each emoji `reaction_type` has an independent namespace for values of `emoji_code`. Must be one of the following values: - `unicode_emoji` : In this namespace, `emoji_code` will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification. - `realm_emoji` : In this namespace, `emoji_code` will be the ID of the uploaded [custom emoji](/help/custom-emoji). - `zulip_extra_emoji` : These are special emoji included with Zulip. In this namespace, `emoji_code` will be the name of the emoji (e.g. "zulip"). EmojiReactionEvent: allOf: - $ref: "#/components/schemas/EmojiBase" - properties: user_id: type: integer description: | The ID of the user who added the reaction. **Changes**: New in Zulip 3.0 (feature level 2). The `user` object is deprecated and will be removed in the future. user: type: object additionalProperties: false deprecated: true description: | Dictionary with data on the user who added the reaction, including the user ID as the `user_id` field. **Changes**: Deprecated and to be removed in a future release once core clients have migrated to use the adjacent `user_id` field, which was introduced in Zulip 3.0 (feature level 2). Clients supporting older Zulip server versions should use the user ID mentioned in the description above as they would the `user_id` field. properties: user_id: type: integer description: | ID of the user. email: type: string description: | Zulip API email of the user. full_name: type: string description: | Full name of the user. is_mirror_dummy: type: boolean description: | Whether the user is a mirror dummy. MessagesEvent: allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: nullable: true client: {} content: {} content_type: {} display_recipient: {} edit_history: {} id: {} is_me_message: {} last_edit_timestamp: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} submessages: {} timestamp: {} topic_links: {} type: {} MessagesBase: type: object description: | Object containing details of the message. properties: avatar_url: type: string nullable: true description: | The URL of the message sender's avatar. Can be `null` only if the current user has access to the sender's real email address and `client_gravatar` was `true`. If `null`, then the sender has not uploaded an avatar in Zulip, and the client can compute the gravatar URL by hashing the sender's email address, which corresponds in this case to their real email address. **Changes**: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, `email_address_visibility` is a user setting. client: type: string description: | A Zulip "client" string, describing what Zulip client sent the message. content: type: string description: | The content/body of the message. content_type: type: string description: | The HTTP `content_type` for the message content. This will be `text/html` or `text/x-markdown`, depending on whether `apply_markdown` was set. display_recipient: oneOf: - type: string - type: array items: type: object additionalProperties: false properties: id: type: integer description: | ID of the user. email: type: string description: | Zulip API email of the user. full_name: type: string description: | Full name of the user. is_mirror_dummy: type: boolean description: | Whether the user is a mirror dummy. description: | Data on the recipient of the message; either the name of a channel or a dictionary containing basic data on the users who received the message. edit_history: type: array items: type: object additionalProperties: false properties: prev_content: type: string description: | Only present if message's content was edited. The content of the message immediately prior to this edit event. prev_rendered_content: type: string description: | Only present if message's content was edited. The rendered HTML representation of `prev_content`. prev_stream: type: integer description: | Only present if message's channel was edited. The channel ID of the message immediately prior to this edit event. **Changes**: New in Zulip 3.0 (feature level 1). prev_topic: type: string description: | Only present if message's topic was edited. The topic of the message immediately prior to this edit event. **Changes**: New in Zulip 5.0 (feature level 118). Previously, this field was called `prev_subject`; clients are recommended to rename `prev_subject` to `prev_topic` if present for compatibility with older Zulip servers. stream: type: integer description: | Only present if message's channel was edited. The ID of the channel containing the message immediately after this edit event. **Changes**: New in Zulip 5.0 (feature level 118). timestamp: type: integer description: | The UNIX timestamp for the edit. topic: type: string description: | Only present if message's topic was edited. The topic of the message immediately after this edit event. **Changes**: New in Zulip 5.0 (feature level 118). user_id: type: integer nullable: true description: | The ID of the user that made the edit. Will be `null` only for edit history events predating March 2017. Clients can display edit history events where this is `null` as modified by either the sender (for content edits) or an unknown user (for topic edits). required: - user_id - timestamp description: | An array of objects, with each object documenting the changes in a previous edit made to the message, ordered chronologically from most recent to least recent edit. Not present if the message has never been edited or if the realm has [disabled viewing of message edit history][disable-edit-history]. Every object will contain `user_id` and `timestamp`. The other fields are optional, and will be present or not depending on whether the channel, topic, and/or message content were modified in the edit event. For example, if only the topic was edited, only `prev_topic` and `topic` will be present in addition to `user_id` and `timestamp`. [disable-edit-history]: /help/disable-message-edit-history **Changes**: In Zulip 10.0 (feature level 284), removed the `prev_rendered_content_version` field as it is an internal server implementation detail not used by any client. id: type: integer description: | The unique message ID. Messages should always be displayed sorted by ID. is_me_message: type: boolean description: | Whether the message is a [/me status message][status-messages] [status-messages]: /help/format-your-message-using-markdown#status-messages last_edit_timestamp: type: integer description: | The UNIX timestamp for when the message was last edited, in UTC seconds. Not present if the message has never been edited. reactions: type: array description: | Data on any reactions to the message. items: $ref: "#/components/schemas/EmojiReaction" recipient_id: type: integer description: | A unique ID for the set of users receiving the message (either a channel or group of users). Useful primarily for hashing. sender_email: type: string description: | The Zulip API email address of the message's sender. sender_full_name: type: string description: | The full name of the message's sender. sender_id: type: integer description: | The user ID of the message's sender. sender_realm_str: type: string description: | A string identifier for the realm the sender is in. Unique only within the context of a given Zulip server. E.g. on `example.zulip.com`, this will be `example`. stream_id: type: integer description: | Only present for channel messages; the ID of the channel. subject: type: string description: | The `topic` of the message. Currently always `""` for direct messages, though this could change if Zulip adds support for topics in direct message conversations. The field name is a legacy holdover from when topics were called "subjects" and will eventually change. submessages: type: array description: | Data used for certain experimental Zulip integrations. items: type: object additionalProperties: false properties: msg_type: type: string description: | The type of the message. content: type: string description: | The new content of the submessage. message_id: type: integer description: | The ID of the message to which the submessage has been added. sender_id: type: integer description: | The ID of the user who sent the message. id: type: integer description: | The ID of the submessage. timestamp: type: integer description: | The UNIX timestamp for when the message was sent, in UTC seconds. topic_links: type: array items: type: object additionalProperties: false properties: text: type: string description: | The original link text present in the topic. url: type: string description: | The expanded target url which the link points to. description: | Data on any links to be included in the `topic` line (these are generated by [custom linkification filters](/help/add-a-custom-linkifier) that match content in the message's topic.) **Changes**: This field contained a list of urls before Zulip 4.0 (feature level 46). New in Zulip 3.0 (feature level 1). Previously, this field was called `subject_links`; clients are recommended to rename `subject_links` to `topic_links` if present for compatibility with older Zulip servers. type: type: string description: | The type of the message: `"stream"` or `"private"`. ModernPresenceFormat: type: object description: | `{user_id}`: Presence data (modern format) for the user with the specified ID. additionalProperties: false properties: active_timestamp: type: integer description: | The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present (e.g. via focusing a browser window or interacting with a computer running the desktop app). Clients should display users with a current `active_timestamp` as fully present. idle_timestamp: type: integer description: | The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients where the user hasn't interacted with the system recently. The Zulip server has no way of distinguishing whether an idle web app user is at their computer, but hasn't interacted with the Zulip tab recently, or simply left their desktop computer on when they left. Thus, clients should display users with a current `idle_timestamp` but no current `active_timestamp` as potentially present. LegacyPresenceFormat: type: object description: | `{client_name}` or `"aggregated"`: Object containing the details of the user's presence. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always contain two keys, `"website"` and `"aggregated"`, with identical data. The server no longer stores which client submitted presence updates. Previously, the `{client_name}` keys for these objects were the names of the different clients where the user was logged in, for example `website` or `ZulipDesktop`. additionalProperties: false properties: client: type: string description: | The client's platform name. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always be `"website"` as the server no longer stores which client submitted presence data. status: type: string enum: - idle - active description: | The status of the user on this client. Will be either `"idle"` or `"active"`. timestamp: type: integer description: | The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second. pushable: type: boolean description: | Whether the client is capable of showing mobile/push notifications to the user. Not present in objects with the `"aggregated"` key. **Changes**: Starting with Zulip 7.0 (feature level 178), always `false` when present as the server no longer stores which client submitted presence data. UserStatus: type: object additionalProperties: false properties: away: type: boolean deprecated: true description: | If present, the user has marked themself "away". **Changes**: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, `away` is a legacy way to access the user's `presence_enabled` setting, with `away = !presence_enabled`. To be removed in a future release. status_text: type: string description: | If present, the text content of the user's status message. emoji_name: type: string description: | If present, the name for the emoji to associate with the user's status. **Changes**: New in Zulip 5.0 (feature level 86). emoji_code: type: string description: | If present, a unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. **Changes**: New in Zulip 5.0 (feature level 86). reaction_type: type: string enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: | If present, a string indicating the type of emoji. Each emoji `reaction_type` has an independent namespace for values of `emoji_code`. Must be one of the following values: - `unicode_emoji` : In this namespace, `emoji_code` will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification. - `realm_emoji` : In this namespace, `emoji_code` will be the ID of the uploaded [custom emoji](/help/custom-emoji). - `zulip_extra_emoji` : These are special emoji included with Zulip. In this namespace, `emoji_code` will be the name of the emoji (e.g. "zulip"). **Changes**: New in Zulip 5.0 (feature level 86). Draft: type: object description: | A dictionary for representing a message draft. properties: id: type: integer description: | The unique ID of the draft. It will only used whenever the drafts are fetched. This field should not be specified when the draft is being created or edited. type: type: string description: | The type of the draft. Either unaddressed (empty string), `"stream"`, or `"private"` (for one-on-one and group direct messages). enum: - "" - stream - private to: type: array description: | An array of the tentative target audience IDs. For channel messages, this should contain exactly 1 ID, the ID of the target channel. For direct messages, this should be an array of target user IDs. For unaddressed drafts, this is ignored, and clients should send an empty array. items: type: integer topic: type: string description: | For channel message drafts, the tentative topic name. For direct or unaddressed messages, this will be ignored and should ideally be the empty string. Should not contain null bytes. content: type: string description: | The body of the draft. Should not contain null bytes. timestamp: type: integer description: | A Unix timestamp (seconds only) representing when the draft was last edited. When creating a draft, this key need not be present and it will be filled in automatically by the server. example: 1595479019 additionalProperties: false required: - type - to - topic - content SavedSnippet: type: object description: | Object containing the details of the saved snippet. additionalProperties: false properties: id: type: integer description: | The unique ID of the saved snippet. title: type: string description: | The title of the saved snippet. content: type: string description: | The content of the saved snippet in text/markdown format. Clients should insert this content into a message when using a saved snippet. date_created: type: integer description: | The UNIX timestamp for when the saved snippet was created, in UTC seconds. ScheduledMessage: type: object description: | Object containing details of the scheduled message. properties: scheduled_message_id: type: integer description: | The unique ID of the scheduled message, which can be used to modify or delete the scheduled message. This is different from the unique ID that the message will have after it is sent. type: type: string description: | The type of the scheduled message. Either `"stream"` or `"private"`. enum: - stream - private to: oneOf: - type: integer - type: array items: type: integer description: | The scheduled message's tentative target audience. For channel messages, it will be the unique ID of the target channel. For direct messages, it will be an array with the target users' IDs. topic: type: string description: | Only present if `type` is `"stream"`. The topic for the channel message. content: type: string description: | The content/body of the scheduled message, in text/markdown format. rendered_content: type: string description: | The content/body of the scheduled message rendered in HTML. scheduled_delivery_timestamp: type: integer description: | The UNIX timestamp for when the message will be sent by the server, in UTC seconds. example: 1595479019 failed: type: boolean description: | Whether the server has tried to send the scheduled message and it failed to successfully send. Clients that support unscheduling and editing scheduled messages should display scheduled messages with `"failed": true` with an indicator that the server failed to send the message at the scheduled time, so that the user is aware of the failure and can get the content of the scheduled message. **Changes**: New in Zulip 7.0 (feature level 181). additionalProperties: false required: - scheduled_message_id - type - to - content - rendered_content - scheduled_delivery_timestamp - failed GroupPermissionSetting: description: | Configuration for a group permission setting specifying the groups to which the setting can be set to and the default values for the setting. additionalProperties: false type: object properties: require_system_group: type: boolean description: | Whether the setting can only be set to a system user group. allow_internet_group: type: boolean description: | Whether the setting can be set to `role:internet` system group. allow_owners_group: type: boolean description: | Whether the setting can be set to `role:owners` system group. allow_nobody_group: type: boolean description: | Whether the setting can be set to `role:nobody` system group. allow_everyone_group: type: boolean description: | Whether the setting can be set to `role:everyone` system group. If false, guest users cannot exercise this permission even if they are part of the [group-setting value](/api/group-setting-values) for this setting. default_group_name: type: string description: | Name of the default group for the setting. id_field_name: type: string description: | Name for the field used to pass the group ID for the setting. default_for_system_groups: type: string nullable: true description: | Name of the default group for the setting for system groups. This is non-null only for group-level settings. allowed_system_groups: type: array description: | An array of names of system groups to which the setting can be set to. If the list is empty, the setting can be set to system groups based on the other boolean fields. **Changes**: New in Zulip 8.0 (feature level 225). items: type: string User: allOf: - $ref: "#/components/schemas/UserBase" - additionalProperties: false properties: user_id: {} delivery_email: nullable: true email: {} full_name: {} date_joined: {} is_active: {} is_owner: {} is_admin: {} is_guest: {} is_billing_admin: {} is_bot: {} bot_type: nullable: true bot_owner_id: nullable: true role: {} timezone: {} avatar_url: nullable: true avatar_version: {} profile_data: {} UserBase: type: object description: | A dictionary containing basic data on a given Zulip user. properties: user_id: type: integer description: | The unique ID of the user. delivery_email: type: string nullable: true description: | The user's real email address. This value will be `null` if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have `email_address_visibility` set to everyone. **Changes**: Prior to Zulip 7.0 (feature level 163), this field was present only when `email_address_visibility` was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when `email_address_visibility` is set to everyone (and therefore not restricted). email: type: string description: | The Zulip API email address of the user or bot. If you do not have permission to view the email address of the target user, this will be a fake email address that is usable for the Zulip API but nothing else. full_name: type: string description: | Full name of the user or bot, used for all display purposes. date_joined: type: string description: | The time the user account was created. is_active: type: boolean description: | A boolean specifying whether the user account has been deactivated. is_owner: type: boolean description: | A boolean specifying whether the user is an organization owner. If true, `is_admin` will also be true. **Changes**: New in Zulip 3.0 (feature level 8). is_admin: type: boolean description: | A boolean specifying whether the user is an organization administrator. is_guest: type: boolean description: | A boolean specifying whether the user is a guest user. is_billing_admin: type: boolean description: | A boolean specifying whether the user is a billing administrator. **Changes**: New in Zulip 5.0 (feature level 73). is_bot: type: boolean description: | A boolean specifying whether the user is a bot or full account. bot_type: type: integer nullable: true description: | An integer describing the type of bot: - `null` if the user isn't a bot. - `1` for a `Generic` bot. - `2` for an `Incoming webhook` bot. - `3` for an `Outgoing webhook` bot. - `4` for an `Embedded` bot. bot_owner_id: type: integer nullable: true description: | If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id` is the user ID of the bot's owner (usually, whoever created the bot). Will be `null` for legacy bots that do not have an owner. **Changes**: New in Zulip 3.0 (feature level 1). In previous versions, there was a `bot_owner` field containing the email address of the bot's owner. role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: | [Organization-level role](/api/roles-and-permissions) of the user. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest **Changes**: New in Zulip 4.0 (feature level 59). timezone: type: string description: | The time zone of the user. avatar_url: type: string nullable: true description: | URL for the user's avatar. Will be `null` if the `client_gravatar` query parameter was set to `true`, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar). **Changes**: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, `email_address_visibility` is a user setting. In Zulip 3.0 (feature level 18), if the client has the `user_avatar_url_field_optional` capability, this will be missing at the server's sole discretion. avatar_version: type: integer description: | Version for the user's avatar. Used for cache-busting requests for the user's avatar. Clients generally shouldn't need to use this; most avatar URLs sent by Zulip will already end with `?v={avatar_version}`. profile_data: $ref: "#/components/schemas/profile_data" profile_data: type: object description: | Only present if `is_bot` is false; bots can't have custom profile fields. A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single `value` key; for those custom profile fields supporting Markdown, a `rendered_value` key will also be present. additionalProperties: type: object additionalProperties: false description: | `{id}`: Object with data about what value the user filled in the custom profile field with that ID. properties: value: type: string description: | User's personal value for this custom profile field. rendered_value: type: string description: | The `value` rendered in HTML. Will only be present for custom profile field types that support Markdown rendering. This user-generated HTML content should be rendered using the same CSS and client-side security protections as are used for message content. JsonResponseBase: type: object properties: result: type: string JsonSuccess: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} example: {"msg": "", "result": "success"} JsonSuccessBase: description: | **Changes**: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an [`ignored_parameters_unsupported`][ignored_params] array. A typical successful JSON response may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters allOf: - $ref: "#/components/schemas/JsonResponseBase" - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: "#/components/schemas/IgnoredParametersUnsupported" IgnoredParametersSuccess: allOf: - $ref: "#/components/schemas/IgnoredParametersBase" - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} description: | **Changes**: The [`ignored_parameters_unsupported`][ignored_params] array was added as a possible return value for all REST API endpoint JSON success responses in Zulip 7.0 (feature level 167). Previously, it was added to [`POST /users/me/subscriptions/properties`](/api/update-subscription-settings) in Zulip 5.0 (feature level 111) and to [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults) in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0 (feature level 78) as a return value for the [`PATCH /settings`](/api/update-settings) endpoint. A typical successful JSON response with ignored parameters may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters example: { "ignored_parameters_unsupported": ["invalid_param_1", "invalid_param_2"], "msg": "", "result": "success", } IgnoredParametersBase: allOf: - $ref: "#/components/schemas/JsonResponseBase" - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: "#/components/schemas/IgnoredParametersUnsupported" ApiKeyResponse: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - required: - api_key - email additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} api_key: type: string description: | The API key that can be used to authenticate as the requested user. email: type: string description: | The email address of the user who owns the API key. user_id: type: integer description: | The unique ID of the user who owns the API key. **Changes**: New in Zulip 7.0 (feature level 171). example: { "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv", "email": "iago@zulip.com", "msg": "", "result": "success", "user_id": 5, } CodedError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} CodedErrorBase: allOf: - $ref: "#/components/schemas/JsonResponseBase" - required: - result - msg - code properties: result: enum: - error msg: type: string code: type: string description: | A string that identifies the error. BadEventQueueIdError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} queue_id: type: string description: | The string that identifies the invalid event queue. example: { "code": "BAD_EVENT_QUEUE_ID", "msg": "Bad event queue ID: fb67bf8a-c031-47cc-84cf-ed80accacda8", "queue_id": "fb67bf8a-c031-47cc-84cf-ed80accacda8", "result": "error", } InvalidMessageError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} example: { "msg": "Invalid message(s)", "code": "BAD_REQUEST", "result": "error", } InvalidChannelError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} example: { "msg": "Invalid channel ID", "code": "BAD_REQUEST", "result": "error", } NonExistingChannelNameError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} stream: type: string description: | The name of the channel that could not be found. example: { "code": "STREAM_DOES_NOT_EXIST", "msg": "Channel 'nonexistent' does not exist", "result": "error", "stream": "nonexistent", } NonExistingChannelIdError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} stream_id: type: integer description: | The channel ID that could not be found. example: { "code": "STREAM_DOES_NOT_EXIST", "msg": "Channel with ID '9' does not exist", "result": "error", "stream_id": 9, } InvalidApiKeyError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "INVALID_API_KEY", "msg": "Invalid API key", "result": "error", } description: | ### Invalid API key A typical failed JSON response for when the API key is invalid. InvitationFailedError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} errors: type: array items: type: array items: oneOf: - type: string - type: boolean description: | An array of arrays of length 3, where each inner array consists of (a) an email address that was skipped while sending invitations, (b) the corresponding error message, and (c) a boolean which is `true` when the email address already uses Zulip and the corresponding user is deactivated in the organization. sent_invitations: description: | A boolean specifying whether any invitations were sent. type: boolean daily_limit_reached: type: boolean description: | A boolean specifying whether the limit on the number of invitations that can be sent in the organization in a day has been reached. license_limit_reached: type: boolean description: | A boolean specifying whether the organization have enough unused Zulip licenses to invite specified number of users. MissingArgumentError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false description: | ### Missing request parameter A typical failed JSON response for when a required request parameter is not supplied. The value of `var_name` contains information about the missing parameter. properties: result: {} msg: {} code: {} var_name: type: string description: | It contains the information about the missing parameter. example: { "code": "REQUEST_VARIABLE_MISSING", "msg": "Missing 'content' argument", "result": "error", "var_name": "content", } IncompatibleParametersError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false description: | ### Incompatible request parameters A typical failed JSON response for when two or more, optional parameters are supplied that are incompatible with each other. The value of `parameters` in the response is string containing the parameters, separated by commas, that are incompatible. properties: result: {} msg: {} code: {} parameters: type: string description: | A string containing the parameters, separated by commas, that are incompatible. example: { "code": "BAD_REQUEST", "msg": "Unsupported parameter combination: object_id, object_name", "result": "error", "parameters": "object_id, object_name", } UserNotAuthorizedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "User not authorized for this query", "result": "error", } description: | ### User not authorized for query A typical failed JSON response for when the user is not authorized for a query. UserDeactivatedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "USER_DEACTIVATED", "msg": "Account is deactivated", "result": "error", } description: | ### User account deactivated A typical failed json response for when user's account is deactivated. **Changes**: As of Zulip 5.0 (feature level 76), these errors use the HTTP 401 status code. Before this feature level, they used the HTTP 403 status code. RateLimitedError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false description: | ### Rate limit exceeded A typical failed JSON response for when a rate limit is exceeded. Zulip sets a few [HTTP response headers][rate-limit-headers] to help with preventing rate limit errors. The value of `retry-after` in the response indicates how many seconds the client must wait before making additional requests. **Changes**: Before Zulip 4.0 (feature level 36), the `code` key was not present in rate limit errors. [rate-limit-headers]: /api/http-headers#rate-limiting-response-headers properties: result: {} msg: {} code: {} retry-after: type: integer description: | How many seconds the client must wait before making additional requests. example: { "code": "RATE_LIMIT_HIT", "msg": "API usage exceeded rate limit", "result": "error", "retry-after": 28.706807374954224, } RealmDeactivatedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "REALM_DEACTIVATED", "msg": "This organization is deactivated", "result": "error", } description: | ### Realm deactivated A typical failed json response for when user's organization is deactivated. **Changes**: As of Zulip 5.0 (feature level 76), these errors use the HTTP 401 status code. Before this feature level, they used the HTTP 403 status code. InvalidPushDeviceTokenError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "INVALID_PUSH_DEVICE_TOKEN", "msg": "Device not recognized", "result": "error", } description: | ## Invalid push device token A typical failed JSON response for when the push device token is not recognized by the Zulip server: InvalidRemotePushDeviceTokenError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "INVALID_REMOTE_PUSH_DEVICE_TOKEN", "msg": "Device not recognized by the push bouncer", "result": "error", } description: | ## Invalid push device token A typical failed JSON response for when the push device token is not recognized by the push notification bouncer: Event_types: description: | A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: - **message** (messages) - **subscription** (changes in your subscriptions) - **realm_user** (changes to users in the organization and their properties, such as their name). If you do not specify this parameter, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `"event_types": ["message"]` Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions. type: array items: type: string example: ["message"] Narrow: description: | A JSON-encoded array of arrays of length 2 indicating the [narrow filter(s)](/api/construct-narrow) for which you'd like to receive events for. For example, to receive events for direct messages (including group direct messages) received by the user, one can use `"narrow": [["is", "dm"]]`. Unlike the API for [fetching messages](/api/get-messages), this narrow parameter is simply a filter on messages that the user receives through their channel subscriptions (or because they are a recipient of a direct message). This means that a client that requests a `narrow` filter of `[["channel", "Denmark"]]` will receive events for new messages sent to that channel while the user is subscribed to that channel. The client will not receive any message events at all if the user is not subscribed to `"Denmark"`. Newly created bot users are not usually subscribed to any channels, so bots using this API need to be [subscribed](/api/subscribe) to any channels whose messages you'd like them to process using this endpoint. See the `all_public_streams` parameter for how to process all public channel messages in an organization. **Changes**: See [changes section](/api/construct-narrow#changes) of search/narrow filter documentation. type: array items: type: array items: type: string default: [] example: [["channel", "Denmark"]] AllPublicChannels: description: | Whether you would like to request message events from all public channels. Useful for workflow bots that you'd like to see all new messages sent to public channels. (You can also subscribe the user to private channels). type: boolean default: false example: true RequiredContent: description: | The content of the message. Clients should use the `max_message_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum message size. type: string example: Hello OptionalContent: description: | The updated content of the target message. Clients should use the `max_message_length` returned by the [`POST /register`](/api/register-queue) endpoint to determine the maximum message size. Note that a message's content and channel cannot be changed at the same time, so sending both `content` and `stream_id` parameters will throw an error. type: string example: Hello ChannelPostPolicy: description: | [Policy][permission-level] for which users can post messages to the channel. - 1 = Any user can post. - 2 = Only administrators can post. - 3 = Only [full members][calc-full-member] can post. - 4 = Only moderators can post. **Changes**: New in Zulip 3.0 (feature level 1), replacing the previous `is_announcement_only` boolean. [permission-level]: /api/roles-and-permissions#permission-levels [calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member type: integer default: 1 example: 2 HistoryPublicToSubscribers: description: | Whether the channel's message history should be available to newly subscribed members, or users can only access messages they actually received while subscribed to the channel. Corresponds to the [shared history](/help/channel-permissions) option in documentation. type: boolean example: false Principals: description: | A list of user IDs (preferred) or Zulip API email addresses of the users to be subscribed to or unsubscribed from the channels specified in the `subscriptions` parameter. If not provided, then the requesting user/bot is subscribed. **Changes**: The integer format is new in Zulip 3.0 (feature level 9). oneOf: - type: array items: type: string - type: array items: type: integer example: ["ZOE@zulip.com"] ReactionType: description: | A string indicating the type of emoji. Each emoji `reaction_type` has an independent namespace for values of `emoji_code`. If an API client is adding/removing a vote on an existing reaction, it should pass this parameter using the value the server provided for the existing reaction for specificity. Supported values: - `unicode_emoji` : In this namespace, `emoji_code` will be a dash-separated hex encoding of the sequence of Unicode codepoints that define this emoji in the Unicode specification. - `realm_emoji` : In this namespace, `emoji_code` will be the ID of the uploaded [custom emoji](/help/custom-emoji). - `zulip_extra_emoji` : These are special emoji included with Zulip. In this namespace, `emoji_code` will be the name of the emoji (e.g. "zulip"). **Changes**: In Zulip 3.0 (feature level 2), this parameter became optional for [custom emoji](/help/custom-emoji); previously, this endpoint assumed `unicode_emoji` if this parameter was not specified. type: string example: "unicode_emoji" EmojiCode: description: | A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. For most API clients, you won't need this, but it's important for Zulip apps to handle rare corner cases when adding/removing votes on an emoji reaction added previously by another user. If the existing reaction was added when the Zulip server was using a previous version of the emoji data mapping between Unicode codepoints and human-readable names, sending the `emoji_code` in the data for the original reaction allows the Zulip server to correctly interpret your upvote as an upvote rather than a reaction with a "different" emoji. type: string example: "1f419" MessageRetentionDays: description: | Number of days that messages sent to this channel will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). Two special string format values are supported: - `"realm_default"`: Return to the organization-level setting. - `"unlimited"`: Retain messages forever. **Changes**: Prior to Zulip 5.0 (feature level 91), retaining messages forever was encoded using `"forever"` instead of `"unlimited"`. New in Zulip 3.0 (feature level 17). oneOf: - type: string - type: integer example: "20" CanRemoveSubscribersGroupId: description: | ID of the [user group](/api/get-user-groups) whose members are allowed to unsubscribe others from the channel. Note that a user who is a member of the specified user group must also [have access](/help/channel-permissions) to the channel in order to unsubscribe others. This setting can currently only be set to user groups that are system groups, except for the system groups named `"role:internet"` and `"role:owners"`. **Changes**: Before Zulip 8.0 (feature level 197), the `can_remove_subscribers_group` setting was named `can_remove_subscribers_group_id`. New in Zulip 7.0 (feature level 161). type: integer example: 20 LinkifierPattern: description: | The [Python regular expression](https://docs.python.org/3/howto/regex.html) that should trigger the linkifier. type: string example: "#(?P